Skip to content

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.

Terminal window
export DEVHUB=https://devhub.example.com # replace with your DevHub base URL
export 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:

Terminal window
curl "$DEVHUB/api/v1/me" -H "Authorization: Bearer $DEVHUB_KEY"

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.

Terminal window
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"}'
Terminal window
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.

Terminal window
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.

Input starts a Turn, the Agent’s work on it. While a Turn runs, more text input joins it instead.

Terminal window
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:

Terminal window
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.

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:

Terminal window
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.pdf

The answer arrives once the file is stored; its id (file_...) goes into fileIds:

Terminal window
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 new Idempotency-Key once 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 a turn_error that says why.

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:

Terminal window
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:

Terminal window
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-calls lists 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.

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.