DevHub API quickstart
The DevHub API lets your own code create Agents, talk to them in Sessions, give them files, and let them call tools your application runs. This guide walks through one complete conversation. openapi.yaml is the reference for every request, answer and error.
The examples use curl and two shell variables. DEVHUB is the DevHub base URL, shown on an Agent’s API tab in DevHub Console; every path in this guide and in the reference is relative to it.
export DEVHUB=https://devhub.example.com # replace with your DevHub base URLexport DEVHUB_KEY=ti_dev_...Every request sends your DevHub Key as Authorization: Bearer $DEVHUB_KEY. The key’s secret is shown once when it is issued; keep it in your backend, never in a browser or app you ship. A revoked key is refused with 401 at once, and the event streams it opened end within a few seconds.
Check the key:
curl "$DEVHUB/api/v1/me" -H "Authorization: Bearer $DEVHUB_KEY"Create an Agent and a Session
Section titled “Create an Agent and a Session”Create an Agent blank, or copy an Official Example that GET /api/v1/examples lists by passing its exampleId. Set its instructions, default models, voice, Session Recall and Official Skills with PATCH /api/v1/agents/{agentId}; GET /api/v1/models lists the text and Realtime models you can name, and GET /api/v1/skills lists the Official Skills you can select, each at the version to pass.
curl -X POST "$DEVHUB/api/v1/agents" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: agent-weather-1' \ -H 'Content-Type: application/json' \ -d '{"name":"Travel helper"}'curl -X PATCH "$DEVHUB/api/v1/agents/agt_..." \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"voice":{"language":"en-US","standingTask":null},"sessionRecall":true,"skills":[{"id":"osk_...","version":1}]}'A Session is one conversation with an Agent. It starts with the Agent’s configuration at that moment; later Agent edits reach new Sessions only.
curl -X POST "$DEVHUB/api/v1/sessions" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: session-trip-1' \ -H 'Content-Type: application/json' \ -d '{"agentId":"agt_..."}'Every request that creates something, or sends input, needs an Idempotency-Key that you choose per item. When an answer is lost, repeat the request with the same key and body: it completes or returns the first result, and never creates a second item. A different body under a used key is refused with 409 idempotency_key_reused.
Send input and follow the Turn
Section titled “Send input and follow the Turn”Input starts a Turn, the Agent’s work on it. While a Turn runs, more text input joins it instead.
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: input-1' \ -H 'Content-Type: application/json' \ -d '{"input":"What should I pack for Paris tomorrow?"}'The answer carries the turnId. Follow the Turn’s events as Server-Sent Events until its turn_finished event, then read the finished Turn:
curl -N "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>/events" -H "Authorization: Bearer $DEVHUB_KEY"curl "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>" -H "Authorization: Bearer $DEVHUB_KEY"Each data line is one JSON event; SessionEvent in the reference lists them. Replace the draft with each assistant_draft rather than appending to it; assistant_message is the saved answer. GET /api/v1/sessions/{sessionId}/events streams the whole Session instead and can resume after a disconnect from the last frame’s id.
The Session timeline can include a platform Handoff Turn with kind: template_handoff. It has an empty userMessages array and, on success, a saved assistant summary. Follow Handoff events on the Session stream. The routes that read, stream or cancel one Turn by ID are for Turns started or steered through DevHub.
Give the Agent files
Section titled “Give the Agent files”Upload a file to the Session, then select it in the input that starts a Turn. Send the bytes as application/octet-stream, with the file’s name and media type in the query:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../files?name=itinerary.pdf&contentType=application/pdf" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: file-itinerary-1' \ -H 'Content-Type: application/octet-stream' \ --data-binary @itinerary.pdfThe answer arrives once the file is stored; its id (file_...) goes into fileIds:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Idempotency-Key: input-2' \ -H 'Content-Type: application/json' \ -d '{"input":"Plan my day from this itinerary.","fileIds":["file_..."]}'- A file is at most 20 MiB, and a Turn selects at most 20 files.
- Only Turns of the Session you uploaded the file to can use it.
- Input with files can only start a Turn. While a Turn runs it is refused with 409
session_has_active_turn; send it again with a newIdempotency-Keyonce that Turn has finished. - A file with an
image/media type is also shown to the model as an image. The Session’s model must accept images, and the platform’s image limits apply; otherwise the Turn fails with aturn_errorthat says why.
Let the Agent call your tools
Section titled “Let the Agent call your tools”Client Tools are functions your application runs for the Agent, such as reading a device sensor or your own database. Declare them on the Session; each declaration is a name, a description the Agent reads, and a JSON Schema for its arguments:
curl -X PUT "$DEVHUB/api/v1/sessions/ses_.../client-tools" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"tools":[{"type":"function","name":"get_weather","description":"Current weather for a city.","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}]}'The PUT replaces the whole set, and a Turn uses the set as it was when the Turn started. To avoid overwriting another client’s change, send the ETag of your last read or replacement as If-Match; a changed set then answers 412.
When the Agent calls a Client Tool, the Turn’s stream carries an agent.session.turn.requires_action event:
{ "type": "agent.session.turn.requires_action", "sessionId": "ses_...", "turnId": "<turnId>", "createdAt": "...", "data": { "event": "client_tool_calls", "seq": 4, "payload": { "calls": [ { "callId": "<callId>", "name": "get_weather", "arguments": { "city": "Paris" }, "deadlineAt": "..." } ] } }}Run the tool and answer every call before its deadlineAt, with its output, or with an error the Agent sees instead:
curl -X POST "$DEVHUB/api/v1/sessions/ses_.../turns/<turnId>/client-tool-results" \ -H "Authorization: Bearer $DEVHUB_KEY" \ -H 'Content-Type: application/json' \ -d '{"callId":"<callId>","output":"Sunny, 24 °C"}'- Answer every call the same way: the Agent chooses whether to wait for a result, and the Turn finishes only after the Agent has seen every outcome.
- A call without a result by its deadline ends with an unknown effect, and the Agent decides how to continue; the platform never repeats a call on its own.
- Sending the same result again is safe. A call that already has a result refuses any other result with 409
client_tool_call_settled, as does a call whose deadline passed. - After a disconnect,
GET /api/v1/sessions/{sessionId}/client-tool-callslists the calls still waiting for a result, whether or not you received their event. Reading it changes nothing: a call without a result by its deadline ends with an unknown effect either way.
Errors and retries
Section titled “Errors and retries”Every error has the same shape, {"error":{"code":"...","message":"..."}}. Branch on code; the message may change. An id that is not one of yours always answers 404 not_found, whether or not it exists. A 503 service_unavailable is temporary: retry later with the same Idempotency-Key.
Input that starts or steers a Turn uses your monthly Credits. Once they are used up, the input is refused with 429 credits_exhausted, whose resetsAt is the start of the next UTC month, when they reset. Client Tool results are still accepted, so a running Turn can finish. A 503 credits_unavailable means DevHub cannot check your Credits right now: retry later with the same Idempotency-Key.