API reference
The full, always-current reference is the interactive OpenAPI/Swagger UI:
- Swagger UI:
/v1/docs - OpenAPI spec (JSON):
/v1/openapi.json— import into Postman, generate clients, etc.
Use the Authorize button in Swagger to paste your mag_… key and try endpoints live.
Endpoint summary
All paths are under /v1. All require Authorization: Bearer mag_… except the docs endpoints.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /v1/organization |
any | Who am I (org, partner name, scopes) |
| GET | /v1/clients |
clients.read |
List clients |
| POST | /v1/clients |
clients.write |
Create a client |
| GET | /v1/clients/{id} |
clients.read |
Get a client (with its submissions) |
| PATCH | /v1/clients/{id} |
clients.write |
Update a client (e.g. rename) |
| DELETE | /v1/clients/{id} |
clients.write |
Delete/archive a client |
| POST | /v1/clients/{id}/documents/prepare |
documents.write |
Request presigned upload targets |
| POST | /v1/clients/{id}/documents/finalize |
documents.write |
Confirm presigned uploads |
| POST | /v1/clients/{id}/documents |
documents.write |
Direct multipart upload |
| POST | /v1/clients/{id}/submissions |
submissions.write |
Create a submission |
| GET | /v1/submissions |
submissions.read |
List submissions (?client_id=, ?status=) |
| GET | /v1/submissions/{id} |
submissions.read |
Get/poll a submission |
Conventions
- IDs are opaque and prefixed:
cli_(client),sub_(submission),doc_(document). Treat them as strings. - Timestamps are ISO‑8601 UTC.
- Versioning: the surface is under
/v1; breaking changes ship under a new version.