<!-- Canonical: https://nitrozen.io/docs/python-sdk -->

> Official Python SDK for the Nitrozen.io changelog API. Pydantic v2 models, full type hints, and ApiException error handling.

[Docs](https://nitrozen.io/docs) / Python SDK

# Python SDK

Official Python client for the Nitrozen.io changelog API.

 [ PyPI: nitrozenio ](https://pypi.org/project/nitrozenio/) [ GitHub ](https://github.com/nitrozenio/nitrozen-python)

## Installation

Requires Python 3.9 or later.

shell

```
pip install nitrozenio
```

## Quick Start

python

```
import nitrozenio
from nitrozenio.api.projects_api import ProjectsApi
from nitrozenio.api.entries_api import EntriesApi

configuration = nitrozenio.Configuration(
    host="https://nitrozen.io/api/v1",
    access_token="YOUR_API_TOKEN",
)

with nitrozenio.ApiClient(configuration) as client:
    # List your projects
    projects_api = ProjectsApi(client)
    response = projects_api.projects_get()
    for project in response.data:
        print(f"{project.id}  {project.name}  ({project.slug})")

    # Create a changelog entry
    entries_api = EntriesApi(client)
    entry = entries_api.projects_project_entries_post(
        project=response.data[0].id,
        entry_input=nitrozenio.EntryInput(
            title="New feature",
            content="We shipped something great.",
            category="new",
        ),
    )
    print(entry.data.title)
```

## Authentication

Create an API token on the [API Tokens](https://nitrozen.io/api-tokens) page, then pass it via `access_token` in the configuration:

python

```
configuration = nitrozenio.Configuration(
    host="https://nitrozen.io/api/v1",
    access_token="YOUR_API_TOKEN",
)
```

Use the client as a context manager to ensure connections are properly closed:

python

```
with nitrozenio.ApiClient(configuration) as client:
    api = ProjectsApi(client)
    response = api.projects_get()
```

## Error Handling

API errors raise `ApiException`, which carries the HTTP status code and raw response body:

python

```
from nitrozenio.exceptions import ApiException

try:
    response = projects_api.projects_project_get(project=999)
except ApiException as e:
    print(e.status)   # e.g. 404
    print(e.reason)   # e.g. "Not Found"
    print(e.body)     # raw JSON error body
```

## Pagination

List endpoints accept `page` and `per_page` parameters and return a `meta` object:

python

```
response = entries_api.projects_project_entries_get(
    project=project_id,
    page=2,
    per_page=20,
)

meta = response.meta
print(f"page {meta.current_page} of {meta.last_page} ({meta.total} total)")

for entry in response.data:
    print(f"{entry.id}  {entry.title}")
```

## API Reference

All URIs are relative to `https://nitrozen.io/api/v1`.

### Authentication

 | Method | HTTP | Description |
|---|---|---|
| AuthenticationApi.tokens\_get() | GET /tokens | List API tokens |
| AuthenticationApi.tokens\_post(body) | POST /tokens | Create an API token |
| AuthenticationApi.tokens\_token\_delete(id) | DELETE /tokens/{token} | Revoke an API token |

### Projects

 | Method | HTTP | Description |
|---|---|---|
| ProjectsApi.projects\_get() | GET /projects | List projects |
| ProjectsApi.projects\_post(body) | POST /projects | Create a project |
| ProjectsApi.projects\_project\_get(id) | GET /projects/{project} | Get a project |
| ProjectsApi.projects\_project\_put(id, body) | PUT /projects/{project} | Update a project |
| ProjectsApi.projects\_project\_delete(id) | DELETE /projects/{project} | Delete a project |

### Entries

 | Method | HTTP | Description |
|---|---|---|
| EntriesApi.projects\_project\_entries\_get(id, page?, per\_page?) | GET /projects/{project}/entries | List entries |
| EntriesApi.projects\_project\_entries\_post(id, body) | POST /projects/{project}/entries | Create an entry |
| EntriesApi.projects\_project\_entries\_entry\_get(pid, eid) | GET …/entries/{entry} | Get an entry |
| EntriesApi.projects\_project\_entries\_entry\_put(pid, eid, body) | PUT …/entries/{entry} | Update an entry |
| EntriesApi.projects\_project\_entries\_entry\_delete(pid, eid) | DELETE …/entries/{entry} | Delete an entry |

### Users

 | Method | HTTP | Description |
|---|---|---|
| UsersApi.user\_get() | GET /user | Get current user |
| UsersApi.user\_usage\_get() | GET /user/usage | Get usage statistics |

### Public

 | Method | HTTP | Description |
|---|---|---|
| PublicApi.public\_projects\_slug\_entries\_get(slug) | GET /public/projects/{slug}/entries | List published entries (no auth) |

 Every project starts with these built-in `category` values: `new` `improvement` `fix` `announcement` Projects on a plan with custom categories enabled can define additional category slugs from the dashboard — any of those slugs are valid here too.