Validate a draft change | Rasen Developer API

curl -X POST https://api.v2.rasen.ai/v1/agents/agent_id/draft/validate \
     -H "If-Match: "draft-17"" \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "prompt": "Confirm the appointment for {{customer_name}}.",
  "settings": {
    "language": "en",
    "first_message": "Hello, I am calling to confirm your appointment.",
    "extraction_fields": [
      {
        "name": "appointment_confirmed",
        "type": "boolean",
        "required": false
      }
    ]
  }
}'

{
  "valid": true,
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "Assign an outbound number to this agent."
    }
  ],
  "warnings": [
    {
      "field": "example",
      "code": "example",
      "message": "Assign an outbound number to this agent."
    }
  ],
  "readiness": {
    "state": "ready",
    "reasons": [
      {
        "code": "example",
        "message": "Assign an outbound number to this agent."
      }
    ]
  }
}

Validates the submitted patch over the current draft without saving or making external calls. If-Match fixes which draft is checked. It does not guarantee a call will be admitted. Retained retrieval_snapshot_id and fallback_source_ids values are checked only for workspace, agent-ownership and source-state eligibility; publication validation derives knowledge from the direct agent library.

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.

Headers

If-MatchstringRequired

Strong ETag from the resource being changed. Draft/tool/variable/publication operations use the complete agent draft ETag; number operations use the number ETag; MCP update uses its own ETag. Never retry a stale edit by blindly using a fresh ETag. Agent identity edits use the identity ETag; knowledge-source reingest uses the source ETag. A stale revision returns 409: draft_conflict for agent, draft, variable, tool, MCP server and publication-token checks; conflict with details.reason=stale_revision for phone numbers and knowledge sources. A missing header returns 428 revision_required. Same-intent replay uses the original If-Match and returns its receipt before checking current revision.

Request

This endpoint expects an object.

promptstringOptional

voiceobjectOptional

settingsobjectOptional

Partial merge of these named settings. Absent fields keep their values. Null resets only nullable fields to platform defaults/unset. Arrays replace their field; extraction_fields=[] removes definitions. No serving-model, checkpoint, temperature or campaign retry knobs. Draft excludes inactive noise-suppression controls.

retrieval_snapshot_idstring or nullOptional<=128 characters

Retained compatibility field. If set, the snapshot must belong to this agent. Publication ignores this field and builds or reuses an immutable snapshot from the direct agent library.

fallback_source_idslist of stringsOptional

Retained compatibility field. Values must identify current fallback sources eligible for this agent: agent-owned sources or linked workspace sources. Publication ignores this field and freezes fallback context from the direct agent library. A write replaces the entire compatibility list.

default_toolsobjectOptional

Per-key merge: each policy you include merges field by field; policies you omit stay unchanged. New built-in policies may be added later; older clients that omit them keep them unchanged. end_call is enabled by default for every agent; only an explicit end_call.enabled=false turns it off. transfer starts disabled with a null destination.

Response headers

X-Request-IdstringOptional

Safe server request correlation ID.

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

Validate a draft change.

validboolean

errorslist of objects

warningslist of objects

readinessobject

A snapshot, not a reservation. Admission rechecks current readiness. Publication, model support, knowledge and phone routing are separate prerequisites. Reasons can include credential_unavailable when the live version has tools that pin a revoked credential version.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

413

Content Too Large Error

428

Precondition Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error