Skip to content

Your first API session ​

Creating a session also accepts its first task. Configure the default profile and make the codex template available first.

json
{
  "namespace": "helpdesk",
  "external_key": "support.example.com:ticket:4821",
  "configuration": {
    "agent": {
      "profile": "default",
      "instructions": "Help the support operator. Explain the likely cause and suggest a reply."
    },
    "sandbox": {
      "template": "codex"
    }
  },
  "messages": [
    {
      "text": "Ticket 4821: the customer cannot export a report. Ask for the error message.",
      "external_key": "support.example.com:event:105",
      "metadata": {
        "ticket_id": 4821,
        "event_id": 105
      }
    }
  ]
}

This uses the default allow_multiple_runs: false. A new session per task is enough for a simple connector. For an ongoing conversation, set it to true when creating the session. An existing session's mode cannot be changed.

Save the JSON as request.json. Set ORPHEUS_API_KEY in your shell to the server's service key and send:

sh
curl --fail-with-body http://localhost:8000/api/v1/sessions \
  -H "Authorization: Bearer $ORPHEUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: helpdesk:ticket:4821:event:105' \
  --data-binary @request.json

The 202 Accepted response contains session_id, run_id and message_id. It confirms admission. Execution results arrive later. Store these identifiers in your system.

namespace groups integration sessions. external_key associates a session with a ticket but does not prevent multiple sessions for that ticket. Use Idempotency-Key for retries.

The task text is in messages[].text. metadata is kept in history and is not passed to the agent. If the agent needs the ticket number, also include it in the text or instructions.

Create session method · Read the result