Read editable draft | Rasen Developer API

{
  "agent_id": "agent_01j00000000000000000000000",
  "revision": "draft-17",
  "prompt": "example",
  "voice": {
    "voice_id": "voice_01j00000000000000000000000"
  },
  "settings": {
    "purpose": null,
    "goals": [],
    "call_direction": null,
    "grammatical_gender": null,
    "additional_context": null,
    "language": "en",
    "agent_name": "example",
    "first_message": "example",
    "timezone": "Asia/Kolkata",
    "max_call_duration_seconds": 60,
    "inactivity_timeout_seconds": 1,
    "user_turn_timeout_ms": 250,
    "ivr_hangup": true,
    "voicemail_detection": true,
    "dtmf_enabled": true,
    "dtmf_timeout_seconds": 1,
    "dtmf_digit_limit": 1,
    "dtmf_termination_key": "#",
    "bg_audio": "office",
    "bg_volume": 0,
    "extraction_fields": [
      {
        "name": "appointment_confirmed",
        "type": "text",
        "description": "example",
        "required": true,
        "choices": [
          "example"
        ]
      }
    ]
  },
  "variables": [
    {
      "key": "customer_name",
      "value": "example",
      "description": "example",
      "sensitivity": "public",
      "redacted": true
    }
  ],
  "tool_ids": [
    "example"
  ],
  "retrieval_snapshot_id": "retrieval_snapshot_01j00000000000000000000000",
  "fallback_source_ids": [
    "example"
  ],
  "referenced_variables": [
    "example"
  ],
  "updated_at": "2026-09-25T10:06:00Z",
  "default_tools": {
    "end_call": {
      "enabled": true
    },
    "transfer": {
      "enabled": true,
      "destination_number": "+12025550123"
    }
  }
}

Returns the complete authoring ETag. The ETag is the publication token. It covers the draft revision, the revision of each bound tool, the revision of each referenced MCP server, each pinned secret version, the direct agent library membership and source state/revision, and the default-tool policy. A change to any of them, including an MCP server edit shared by several agents, changes the token.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Path parameters

agent_idstringRequired1-128 characters

Resource identity within the authenticated workspace.

Response headers

X-Request-IdstringOptional

Safe server request correlation ID.

ETagstringOptional

Publication token: covers the draft revision, bound tool revisions, referenced MCP server revisions, pinned secret versions, the direct agent library membership and source state/revision, and the default-tool policy. Send it as If-Match to publishAgent and to draft edits.

RateLimit-LimitintegerOptional

Requests allowed in the current window for the tightest applicable limit.

RateLimit-RemainingintegerOptional

Requests left in the current window.

RateLimit-ResetintegerOptional

Seconds until the current window resets.

Response

Read editable draft.

agent_idstring<=128 characters

Opaque agent identifier. Do not parse its contents.

revisionstring

Opaque publication token; equals the ETag. The ETag is the publication token. It covers the draft revision, the revision of each bound tool, the revision of each referenced MCP server, each pinned secret version, the direct agent library membership and source state/revision, and the default-tool policy. A change to any of them, including an MCP server edit shared by several agents, changes the token.

promptstring

voiceobject

settingsobject

Effective settings after defaults resolve. Not a PATCH input.

variableslist of objects

tool_idslist of strings

retrieval_snapshot_idstring or null<=128 characters

Retained compatibility value. Publication does not read it.

fallback_source_idslist of strings

Retained compatibility values. Publication does not read them.

referenced_variableslist of strings

Discovered prompt references, not a guarantee of required-input validation. Undeclared per-call variables remain accepted.

updated_atdatetime

default_toolsobject

Effective built-in policies. end_call is enabled by default for every agent, including agents created before this field existed; only an explicit end_call.enabled=false policy turns it off. transfer starts disabled with a null destination. Publication freezes the policy; rollback restores it subject to current revocation. Clients must accept additional policy keys.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error