Build with your agent.

An agent is an AI model we set up for one job of yours. Its instructions, tone and limits are built in: you send it the material to work on (an email, an invoice, a lead) and it sends back the result.

• Base URL: https://atelieragents.com/v1
• Model: your agent's id, for example invoice-clerk. Each key belongs to one agent, and responses always name it in model.
• Format: JSON over HTTP, in the OpenAI chat completions shape.
• Billing: per token, read and written. See Tokens and billing.

Send your key with every request, in either of these headers:

• Keys start with ak_. Your portal shows only their first characters; the full key is in the email we sent you.
• Keep keys server-side: in an environment variable, a secret store, or your tool's credentials. The API accepts calls from browsers (CORS), but a key placed in a web page or a mobile app can be read by anyone, and spent.
• Use one key per integration so usage is easy to tell apart. Ask us for more keys.
• We cannot show a key again. If one is lost, write to us: we revoke it and issue a new one. If one was exposed, tell us: we also reset your portal link, which signs out every open portal session, and email you the new link.
• A missing, mistyped or revoked key gets 401 with the code invalid_api_key.

The request and response follow the OpenAI chat completions format, so existing code keeps working with a new base URL. The model you send is accepted and ignored: your key decides which agent answers, and the response names it.

Your agent's own instructions are always sent first, and a call cannot remove or replace them. If you send system (or developer) messages, their text is added after the agent's instructions, under the heading "Additional instructions from the caller". Use them for context that changes from call to call: the language to answer in, today's date, a customer's name.

response_format, tools and tool_choice reach your agent unchanged. Whether an answer follows a JSON format or calls one of your tools depends on how your agent was built: if your integration relies on it, tell us and we test it with you.

Set "stream": true to receive the answer while it is written, as server-sent events. Each event is a line that starts with data: followed by a JSON chunk, and the stream ends with data: [DONE].

• Add "stream_options": {"include_usage": true} to receive a last chunk with empty choices and the usage of the whole answer. When you ask for it, it is sent at the end of every stream, except when the stream is interrupted (see below).
• Streamed responses cannot carry the X-Tokens-Used, X-Cost and X-Balance headers: headers leave before the answer is written. Read the final usage chunk, or call GET /v1/usage for your balance.
• If you close the connection early, the tokens generated so far are billed.
• A stream may start with comment lines (: keepalive) while your agent prepares its answer, and they can also come between chunks. SSE clients and the OpenAI SDKs ignore them.
• If the agent fails before the stream starts, you get a normal JSON error with an HTTP status (see Errors). If it fails after the stream has started, the stream ends with an error event and data: [DONE], without a usage chunk. Its code tells what happened: upstream_unavailable, upstream_timeout or server_busy when no token was sent yet (nothing billed), upstream_interrupted when your agent stopped answering midway, or internal_error for an unexpected error on our side. After an interruption the tokens produced so far are billed: your portal and GET /v1/usage show them.

The shortest path from a no-code tool or a script: send text, get text back in output, with the cost of the call in the same response.

• billing.cost and billing.balance are strings in EUR, included_tokens_remaining counts the included tokens left in your period. In rare cases billing is null; the answer is still valid.
• Streaming, tools and response_format are not available here. Use chat completions for them.

The list holds one model: the agent your key calls. Its id is the value to send as model. /v1/models/{id} returns that card, or 404 model_not_found for any other id.

Your balance, plan, included tokens and usage for the current month, in one call. It does not cost anything.

The Download CSV button on the Usage page of your portal gives one row per call for the period you picked. The English file uses commas and a decimal point, with the column names below. The French portal gives the same columns with French headers, semicolons and decimal commas, so it opens in columns in French spreadsheet apps.

Errors use the OpenAI error shape, so SDKs raise them with our message. The code field tells you what happened.

Your keys have no limit on calls per minute unless we agreed on one with you, so a large batch or a busy agent is never slowed down by a counter. Your balance still applies, and your portal shows the limit, if any, next to each key. When a key has a limit, the window slides and counts the calls of the last 60 seconds.

• Over the limit of a key that has one, a call gets 429 with a Retry-After header, in seconds.
• /v1/models and /v1/usage have their own counter with the same limit, so checking your balance never uses up your call budget.
• At busy moments, a call can wait a few seconds before your agent starts on it. If no slot frees up in time, it gets 503 server_busy with a Retry-After header, and nothing is billed.

Calls are accepted while you have included tokens left, or while your balance plus any agreed credit line is above zero. The last call can take the balance slightly below zero; the next one gets 402 insufficient_quota.

Calls that are still running count against your balance, so when it is almost used up, parallel calls may get 402 insufficient_quota before the first one finishes. Retry when they finish.

On a plan paid online, calls keep going through for up to 7 days after the period ends while the renewal is being paid. Once it is paid, they count against the new period.

When the money you can spend (your balance plus any credit line) drops under €2.00, we email you once. The alert re-arms after you top up.

If your agent does not report exact token counts for a call, we estimate them from the length of the text, at about 4 characters per token. Those calls are marked "estimated" in your portal and in the usage CSV.

Any OpenAI-compatible client works: set its base URL to https://atelieragents.com/v1 and the model to your agent's id.

Make, Zapier, n8n and similar tools call your agent with their HTTP request step. Use the simple run endpoint with these settings:

• Labels differ between versions of these tools; the settings above stay the same.
• When you insert a field inside the JSON body, make sure quotes and line breaks in the text are escaped. Most tools offer a JSON-safe insert.
• Many tools stop waiting after 30 to 60 seconds. Add "max_tokens": 400 (or what you need) to the body to keep calls short.