RACO · APIReference
Agent Pack + Agent Turn APIDevelopersOpenAPI

Use case

Authorable, no-send collections conversations

RACO decides one bounded conversation turn from an immutable active Agent Pack. Enabled business intents, account stages, payment asks, attempt sources, escalation policies, conversation plans, and action definitions are authored in Studio.

Every collections response, handoff, pause, payment hierarchy, approval mode, test threshold, and rollout target comes from the authored Agent Pack. The platform owns only authentication, tenant isolation, trusted data, schema integrity, resource limits, idempotency, and no-send mechanics.

Agent Turn calls do not send messages or execute account actions. Live account and legal facts are resolved by trusted server adapters; external callers cannot inject them into a decision request.

Workflow

One turn at a time

  1. Author and testAn editor saves an Agent Pack draft and simulates an exact draft revision with fictional scalar fact fixtures.POST /raco/agent-packs/draft/save · /raco/agent-turns/simulate
  2. Approve and activateTrusted evidence and canary configuration are bound to an immutable draft revision before activation.POST /raco/agent-packs/canary/activate
  3. Decide one turnThe live route resolves trusted context, applies the active canary Agent Pack, and returns a redacted no-send result.POST /raco/agent-turns/decide
  4. Record verified outcomesDelivery, payment, promise, review, dispute, opt-out, and handoff events enter through the closed event contract.POST /raco/events

Access

Firebase bearer token or scoped RACO API client

Authorization: Bearer <firebase-id-token>
Authorization: RacoClient <clientId>:<clientSecret>
  • Studio, Agent Pack, project, membership, provider-setting, and action-proposal routes require a signed-in Firebase user with project access.
  • External clients may call only /raco/agent-turns/decide with agent_turn_decide scope or /raco/events with event_ingest scope.
  • External client secrets are shown once, stored as hashes, bound to one project, rate-limited, and auditable.
  • Live Agent Turns and outcome events require a bounded idempotencyKey in the JSON body. Reusing a key for different content fails closed.
  • External clients cannot read drafts, activate Agent Packs, manage projects, approve actions, or access provider credentials.

Endpoints

Implemented routes

POST/raco/agent-turns/decide

Decide one live, no-send Agent Turn

Requires editor or owner live-decision permission, or an external client with agent_turn_decide, plus an active eligible Agent Pack and fresh trusted live context. The provider may classify only enabled authored intents; there are no reserved platform intents or hidden business routes. Caller-supplied packs, account facts, legal trust, provider payloads, and hidden state are rejected.

Request body

Field
Type
Limit
Note
schemaVersionreq
const
raco_agent_turn_request_v1
Closed Agent Turn request schema
projectIdreq
string
1–80
Project-scoped safe identifier
caseIdreq
string
1–120
Stable case identifier
conversationIdreq
string
1–120
Stable conversation identifier
messageIdreq
string
1–100
Stable inbound-message identifier
channelreq
enum
sms | email | chat | voice | whatsapp | other
Conversation channel; never triggers delivery
debtorMessagereq
string
1–2,000
Bounded inbound text without control characters
idempotencyKeyreq
string
1–160
Replay-safe live-turn key

Response

Field
Type
Limit
Note
ok
boolean
—
true when the turn was decided
sent
const
false
Agent Turn routes never deliver messages
status
enum
decided | simulated
Operation result
decision
object
—
Redacted pack, understanding, obligations, compliance, route, plan, negotiation, and action proposals
reply
object | null
—
Validated no-send reply, or null when composition is unavailable or the route is not composable
api
object
—
No-send operation and live canary provenance

Example

curl -i -sS "$RACO_API/raco/agent-turns/decide" \
  -H "Authorization: RacoClient $RACO_CLIENT_ID:$RACO_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": "raco_agent_turn_request_v1",
    "projectId": "raco_proj_example",
    "caseId": "loan-7821",
    "conversationId": "conv_loan_7821",
    "messageId": "msg_7821",
    "idempotencyKey": "agent_turn_msg_7821",
    "channel": "sms",
    "debtorMessage": "I can maybe do 100 next Friday."
  }'
POST/raco/agent-turns/simulate

Simulate one no-send turn against an exact draft

Firebase project-member route for viewers, editors, and owners. It loads the saved draft at expectedDraftRevision and accepts bounded fictional account facts plus prior-conversation state for counters, stages, outcomes, and transitions. External clients cannot simulate and simulation proposals cannot execute.

Request body

Field
Type
Limit
Note
schemaVersionreq
const
raco_agent_turn_request_v1
Closed Agent Turn request schema
projectIdreq
string
1–80
Project-scoped safe identifier
caseIdreq
string
1–120
Stable case identifier
conversationIdreq
string
1–120
Stable conversation identifier
messageIdreq
string
1–100
Stable inbound-message identifier
channelreq
enum
sms | email | chat | voice | whatsapp | other
Conversation channel; never triggers delivery
debtorMessagereq
string
1–2,000
Bounded inbound text without control characters
expectedDraftRevisionreq
integer
1–1,000,000,000
Exact saved revision to test
accountFactFixtures
object
≤80 scalar entries
Fictional string, number, or boolean fixtures; never returned or logged
stateFixtures
object
≤32 scalar entries
Fictional conversation, outcome, or behavior state; simulation only

Response

Field
Type
Limit
Note
ok
boolean
—
true when the turn was decided
sent
const
false
Agent Turn routes never deliver messages
status
enum
decided | simulated
Operation result
decision
object
—
Redacted pack, understanding, obligations, compliance, route, plan, negotiation, and action proposals
reply
object | null
—
Validated no-send reply, or null when composition is unavailable or the route is not composable
api
object
—
No-send operation and live canary provenance

Example

curl -i -sS "$RACO_API/raco/agent-turns/simulate" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": "raco_agent_turn_request_v1",
    "projectId": "raco_proj_example",
    "caseId": "fictional-case-1",
    "conversationId": "fictional-conversation-1",
    "messageId": "fictional-message-1",
    "channel": "chat",
    "debtorMessage": "What payment options are available?",
    "expectedDraftRevision": 7,
    "accountFactFixtures": { "days_past_due": 30 },
    "stateFixtures": { "conversationState.paymentAskCount": 2, "outcomeState.promise.status": "broken" }
  }'
POST/raco/events

Ingest one verified outcome event

Accepts the closed outcome taxonomy for message, payment, promise, review, opt-out, dispute, and handoff lifecycle facts. Raw messages, transcripts, credentials, provider payloads, and unknown fields are rejected.

Request body

Field
Type
Limit
Note
eventIdreq
string
≤120
Stable event identifier
eventTypereq
enum
closed outcome taxonomy
For example payment.succeeded or promise.broken
projectIdreq
string
1–80
Project-scoped safe identifier
caseIdreq
string
≤120
Owning case
conversationIdreq
string
≤120
Owning conversation
occurredAtreq
ISO-8601
timezone required
Cannot be more than five minutes in the future
sourcereq
string
safe id
Trusted event producer
correlationreq
object
closed fields
decisionId, messageId, connectorExecutionId, or externalId
idempotencyKeyreq
string
≤160
Replay-safe event key
datareq
object
event-specific schema
Typed data allowed for the selected eventType

Response

Field
Type
Limit
Note
ok
boolean
—
true when accepted or safely replayed
event
object
—
Normalized outcome event
api
object
—
No-send event-ingest envelope

Example

curl -i -sS "$RACO_API/raco/events" \
  -H "Authorization: RacoClient $RACO_CLIENT_ID:$RACO_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "payment-event-7821",
    "eventType": "payment.succeeded",
    "projectId": "raco_proj_example",
    "caseId": "loan-7821",
    "conversationId": "conv_loan_7821",
    "occurredAt": "2026-07-15T08:00:00Z",
    "source": "payment_ledger",
    "correlation": { "decisionId": "decision-7821" },
    "idempotencyKey": "payment-event-7821",
    "data": { "paymentId": "payment-7821", "amountMinor": 10000, "currency": "PHP" }
  }'
POST/raco/action-proposals/create

Create a bounded account-action proposal

Creates proposal state only. It does not execute an action. The referenced action must be authorized by the immutable decision and Agent Pack before later approval or execution transitions can proceed.

Request body

Field
Type
Limit
Note
projectIdreq
string
1–80
Project-scoped safe identifier
caseIdreq
string
≤120
Owning case
conversationIdreq
string
≤120
Owning conversation
decisionIdreq
string
≤120
Authoritative Agent Turn decision
actionIdreq
string
≤80
Authored action id
idempotencyKeyreq
string
≤160
Replay-safe proposal key

Response

Field
Type
Limit
Note
proposal
object
—
Versioned proposal with approval state
executed
const
false
Create never executes an account action
api
object
—
No-send action-proposal envelope

Example

curl -i -sS "$RACO_API/raco/action-proposals/create" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "raco_proj_example",
    "caseId": "loan-7821",
    "conversationId": "conv_loan_7821",
    "decisionId": "decision-7821",
    "actionId": "record_promise",
    "idempotencyKey": "proposal-decision-7821-record-promise"
  }'
POST/raco/agent-packs/draft/read

Read the project Agent Pack draft

Returns the normalized draft and revision receipt for an authorized Studio user. External API clients cannot read drafts.

Request body

Field
Type
Limit
Note
projectIdreq
string
1–80
Project-scoped safe identifier

Response

Field
Type
Limit
Note
agentPack
object
—
Normalized draft Agent Pack
receipt
object
—
Project, pack, version, and revision binding
api
object
—
No-send Agent Pack envelope

Example

curl -i -sS "$RACO_API/raco/agent-packs/draft/read" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "raco_proj_example" }'
POST/raco/agent-packs/active/read

Read active Agent Pack launch state

Returns the immutable active Agent Pack and trusted canary provenance for an authorized project user.

Request body

Field
Type
Limit
Note
projectIdreq
string
1–80
Project-scoped safe identifier

Response

Field
Type
Limit
Note
agentPack
object
—
Immutable active Agent Pack
launch
object
—
Bound launch evidence and canary configuration
api
object
—
No-send Agent Pack envelope

Example

curl -i -sS "$RACO_API/raco/agent-packs/active/read" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "raco_proj_example" }'

Errors

HTTP status mapping

Status
Code
When
400
invalid-argument
Missing, malformed, unknown, unsafe, or over-limit input.
401
unauthenticated
Missing or invalid Firebase token or RACO client credential.
403
permission-denied
Project role, client scope, origin, or route is not allowed.
404
not-found
Unknown exact route or missing project-scoped resource.
409
aborted
Optimistic revision or proposal version changed.
412
failed-precondition
Agent Pack, launch, canary, context, approval, or policy prerequisite is unmet.
429
resource-exhausted
Principal rate limit or durable quota was exceeded.
500
internal
Redacted server failure; retry only with the same idempotency key.

Server boundary

No backend paths in client config

RACO exposes project ids and versioned response envelopes to caller apps. Storage paths, provider secrets, hidden prompts, and internal audit locations stay behind the trusted Function API.

  • Only exact allowlisted routes are accepted; retired aliases and compatibility paths return not-found.
  • Live callers cannot inject Agent Packs, account facts, legal trust, model prompts, provider payloads, or internal state.
  • Only account facts declared non-sensitive and enabled for replies may enter the reply-composition context.
  • OpenAI and Anthropic credentials are write-only project settings and never enter Agent Packs, browser storage, API responses, or logs.
  • Provider output cannot create new intent types, alter authored policies, authorize or execute actions, or bypass the pack's authored readiness criteria.
  • Action proposal execution is a separate authenticated lifecycle; Agent Turn output always reports executionAvailable as false.