API Reference

Core conventions for working with the Configo API — versioning, authentication, request format, and error handling.

Base URL

All API requests are made to:

https://configo.org/api

API versioning

The Configo API is versioned via the URL path. The current and only available version is v1:

https://configo.org/api/v1/...

Availability

The API is available on every Configo plan, including the trial. A project's data can be reached only while the project owner's subscription is active.

Authentication

The Configo API uses OAuth 2.0. Authenticate your requests by including an access token in the Authorization header as a Bearer token:

Authorization: Bearer <access_token>

Requests without a valid token, or with an expired or revoked token, will receive a 401 Unauthorized response. How to obtain and refresh tokens is described in Authentication.

Scopes

Access tokens are issued with one or more scopes, which determine what parts of the API the token can access. Every request is checked against the scopes required by the endpoint — all required scopes must be present on the token, not just one of them.

Scope	Grants access to
`identify`	The user's profile, connected accounts, referrals, locale and notifications (User)
`billing`	Subscription, plans, payments and balance (Billing)
`files`	Uploading, retrieving and deleting files (Files)
`projects`	Projects and their settings: funnels, statuses, loss reasons, contact fields (Projects, Funnels & statuses)
`members`	Project members, invitations and roles (Members & roles)
`orders`	Orders (Orders)
`clients`	Contacts, companies and tags (Contacts, Companies)
`tasks`	Tasks (Tasks)
`reports`	Reports (Reports)
`materials`	Materials (Materials)
`configurators`	Configurators and the public showcase (Configurators)
`products`	Products (Products)
`warehouses`	Warehouses and stock (Warehouses)
`wiki`	The wiki (Wiki)
`documents`	Document templates (Document templates)
`email_templates`	Email templates and the mail sender (Email)
`automations`	Automations (Automations)

Endpoints under /api/v1/projects/{project.uuid}/ require both the projects scope and the resource's own scope, since access is evaluated in the context of a project.

Read and write

A scope can be granted for reading only, or for reading and writing. A request that changes something (POST, PUT, PATCH, DELETE; a POST that only calculates, such as a configurator calculation, counts as a read) needs the resource's scope with write access. In the scope string a plain name means read, and name:write means read and write: projects orders:write reads projects and reads and writes orders.

Under /api/v1/projects/{project.uuid}/ the projects scope is only the access to the project, so a write needs write access to the resource's own scope. Project settings are guarded by projects alone, so changing them takes write access to projects, which an application that registered itself (see MCP server) never gets. A request that needs more than the token allows is answered with 403 AUTH_INSUFFICIENT_SCOPE.

Applications that existed before this split, and numeric scope values, keep working as before: they write wherever they read.

Role permissions

Scopes limit what your application may do. What the user may do inside a project is limited by their project role, a set of permissions such as can_view_all_orders or can_edit_clients. A request needs both: the right scope on the token and the right permission in the user's role. The project owner has every permission. Each entity page lists the permissions its endpoints need.

Pagination

List endpoints that can return many items take page (from 1) and limit query parameters. Two response shapes are in use:

A plain array (orders, contacts, tasks): request the next page until a page comes back shorter than limit.
An envelope {data, page, limit, total, total_pages} (materials, products, warehouse stock).

Each list endpoint states its default and maximum limit.

Rate limits

What	Limit	Response
Failed client authentication at `/api/auth/token` and `/api/auth/token/revoke`	20 failures per `client_id` per 15 minutes	`429 slow_down`, `Retry-After: 900`
Dynamic client registration (`/oauth/register`)	500 registrations per hour, all callers together	`429 slow_down` with `Retry-After`
Widget orders (`POST /api/v1/widget/orders`)	60 per minute per project	`429 {"message": "Too many requests"}`
Any other `/api/v1` request with a bearer token	600 per minute per user and client	`429 {"message": "Too many requests"}`, `Retry-After`

Back off when you receive 429 and wait for Retry-After seconds if it is present.

Request format

User-Agent

All requests must include a User-Agent header identifying the client library and its version:

User-Agent: ConfigoClient (library, version)

Content-Type

Requests that include a body must specify a valid Content-Type header:

application/json
application/x-www-form-urlencoded
multipart/form-data

Field notation

Entity pages describe fields in tables using this notation:

Notation	Meaning
`field?`	The field is optional and may be omitted
`?type`	The value may be `null`
uuid	A UUID string, e.g. `0199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11`
ISO8601 datetime	A UTC timestamp, e.g. `2026-10-01T09:30:00.000Z`
decimal	A JSON number

HTTP methods

The API uses standard HTTP methods to indicate the action being performed:

Method	Action
`GET`	Retrieve one or more resources
`POST`	Create a new resource
`PUT`	Replace a resource entirely
`PATCH`	Update part of a resource
`DELETE`	Delete a resource

Response codes

Errors carry a JSON body with a numeric id, a code and a message; see Errors for the format and the full list.

Code	Meaning
`200 OK`	The request completed successfully.
`201 CREATED`	The resource was created successfully.
`204 NO CONTENT`	The request completed successfully but returned no content.
`304 NOT MODIFIED`	The resource was not modified; no action was taken.
`400 BAD REQUEST`	The request was malformed or could not be understood.
`401 UNAUTHORIZED`	The `Authorization` header is missing or invalid.
`403 FORBIDDEN`	The token does not have permission to access this resource.
`404 NOT FOUND`	The requested resource does not exist.
`405 METHOD NOT ALLOWED`	The HTTP method is not supported for this endpoint.
`409 CONFLICT`	The resource already exists.
`429 TOO MANY REQUESTS`	You are being rate limited.
`502 GATEWAY UNAVAILABLE`	No gateway was available to process the request. Wait and retry.
`5xx SERVER ERROR`	An error occurred on Configo's side. These are rare.

Endpoints under /api/v1/widget use a separate authentication scheme, intended for embedding Configo on a public-facing website rather than for OAuth-based integrations. These requests are authenticated with a project-specific widget token, passed via the X-Widget-Token header:

X-Widget-Token: <jwt>

See Widget API.