AI Agents — API overview

Everything you can do from the portal’s AI Agents tab is also exposed as a public REST API under /v1. Use it to provision agents from your own dashboards, run migrations, wire CI, or build multi-tenant products where each of your customers gets their own agent without a human touching the portal.

The five resources

Lifecycle

┌──────────┐   ┌───────────┐   ┌───────────────┐   ┌───────────────┐
│  Agent   │──▶│ AgentTool │──▶│ AgentVersion  │──▶│ AgentBinding  │
│  (name,  │   │  (HTTP    │   │ (prompt +     │   │ (scope +      │
│  model)  │   │  contract)│   │  tools + gr.) │   │  secrets)     │
└──────────┘   └───────────┘   └───────────────┘   └───────────────┘
                                        │                  │
                                        │                  ▼
                                        │           ┌──────────────┐
                                        │           │ AgentThread  │
                                        │           │ (per conv,   │
                                        │           │  auto-created)│
                                        │           └──────────────┘
                                        │
                                        └─ Roll a new version = new record,
                                           existing bindings unchanged.

Runtime is transparent: when a message hits a phone_number that has a matching active AgentBinding, the runtime resolves the version, hydrates tools + secrets, runs the LLM loop, calls your endpoints when the model asks for them, and replies as source=AUTO_AGENT_PLATFORM. You never write orchestration code.

Quickstart — provision an agent end-to-end

curl -X POST https://cloud.gosendapi.com/v1/agents \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Booking assistant",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "description": "Handles appointment booking over WhatsApp."
  }'
# → { "id": "agt_...", "name": "Booking assistant", ... }

curl -X POST https://cloud.gosendapi.com/v1/agent-tools \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "booking.search",
    "description": "Search available slots.",
    "declaration": { /* five blocks — see agents-tools guide */ }
  }'
# → { "id": "tool_...", "slug": "booking.search", ... }

curl -X POST https://cloud.gosendapi.com/v1/agents/$AGENT_ID/versions \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are the booking assistant of ...",
    "tools": ["booking.search", "booking.create"],
    "guardrails_config": { "capExecucion": 10, "capConversacion": 20 }
  }'
# → { "id": "ver_...", "version": 1, ... }

curl -X POST https://cloud.gosendapi.com/v1/agent-bindings \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fitz Roy Clinic — pilot",
    "agent_version_id": "ver_...",
    "scope": "phone_number",
    "phone_number_id": "phn_...",
    "params": { "wizardEnabled": false, "catchAllAction": "escalate" },
    "reglas": { "tono": "Cordial, use vos.", "identidadIA": "Say you are the virtual assistant if asked." }
  }'
# → { "id": "bnd_...", "has_secrets": false, ... }

curl -X POST https://cloud.gosendapi.com/v1/admin/agent-bindings/$BINDING_ID/secrets \
  -H "X-Admin-Key: $GOSENDAPI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": {
      "erp_api_key": "sk_live_...",
      "erp_tenant_slug": "fitzroy"
    }
  }'

That’s it — the next inbound message on that phone number goes through the agent loop.

Rules vs Params vs Secrets

Three separate JSON objects on AgentBinding, each with a different consumer:

The most common mistake: putting catchAllAction in reglas and expecting the runtime to change behavior — it won’t. reglas only affects what the model says.

Documented params keys

Only these keys have runtime effect (anything else is silently ignored):

Versioning strategy

AgentVersion is immutable so you get safe rollouts without infrastructure:

• Pilot a new prompt — create v2, point one binding at it. If the pilot succeeds, PATCH the other bindings’ agent_version_id.
• A/B testing — same version across bindings; different reglas per binding for tone/copy variants.
• Emergency rollback — one PATCH per binding back to the previous version. No code deploy.
• Clone & edit — duplicate a version (portal has a shortcut; via API, GET the version, POST a new one with tweaks).

You cannot mutate a version’s system_prompt, tools, guardrails_config, or routing. Attempting a PATCH will fail with 405. Delete only works if no bindings still reference it.

Guardrails floor

Every run passes through non-negotiable checks before, during and after the LLM loop:

1. Urgency detector — Spanish medical patterns (respiratory, cardiac, neuro, bleeding, suicide, death-imminent, child+symptom, explicit urgente/emergencia/SOS). Match → thread muted as handoff.
2. Human intervention scan — if a human replied in the last 24h via HUMAN_COEXISTENCE (mobile) or HUMAN_PORTAL → thread muted as human_detected.
3. Conversation cap — default 20 messages (30 for platform-managed). Prevents runaway loops.
4. Cost circuit breaker — per-thread ($1 default), per-tenant per-day ($50 default), per-tenant per-month ($500 default). Overridable per tenant.
5. Output safety — if the LLM claims a factual action (“your appointment is booked”) without a successful matching tool call, the reply is blocked before send.

Every muting event is durable — see the next section for reactivation.

Reactivating a muted thread

Every mute has an explicit muted_reason so the runtime knows what kind of unmute (if any) is safe. These are the exact string values you get back in the muted_reason field of GET /v1/agent-threads:

Manual reactivation via API works for any reason (overrides the “no auto-unmute” categories):

Related: resetting the message history

Reactivation clears the muted state. It does not clear AgentThread.messages. If you’re iterating on the system prompt and the accumulated history is making the model replay old patterns (see Milestone tools & auto-reset), reset the history separately:

curl -X POST https://cloud.gosendapi.com/v1/agent-threads/$THREAD_ID/reset-messages \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "iterating booking flow prompt to v23"}'

This clears messages to [] and emits AgentEvent thread.messages_reset for audit. It does NOT unmute — use /reactivate for that.

# List every muted thread for your tenant
curl https://cloud.gosendapi.com/v1/agent-threads?muted=true \
  -H "X-API-Key: $GOSENDAPI_KEY"
 
# Reactivate one
curl -X POST https://cloud.gosendapi.com/v1/agent-threads/$THREAD_ID/reactivate \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "False positive from urgency detector — patient just asked if it was a bot."}'

The reactivation is atomic (mutedAt=NULL, mutedReason=NULL) and emits an AgentEvent thread.reactivated for audit — previous_muted_reason, reactivated_by_user_id, reason. Idempotent: reactivating an already-active thread is a no-op, no event emitted.

Detecting silent human intervention

Beyond the explicit handoff mechanism, the runtime scans the last 24h of each conversation for any message that came from a human channel and mutes the thread with human_detected if it finds one. The three channels the scan recognises:

If any of the three appear within the window, the agent stays silent. The reason is auto-reset later (see the inactivity reset matrix).

Housekeeping — inactive thread reset

AgentThread.messages grows every turn — the assistant reply plus each tool result gets appended. Without housekeeping the array grows forever, and every subsequent run pays the token cost of the whole history plus risks pattern replay from stale content (see milestone tools & auto-reset).

Three mechanisms clear it:

Tuning inactiveResetDays per binding

Different bindings on the same tenant can pick different windows depending on the vertical:

• Booking / appointments — 2 to 3 days. A patient that comes back a week later is almost always starting a new topic.
• Support / troubleshooting — 5 to 7 days. Longer troubleshooting arcs where multi-day context is useful.
• Notifications-only — set 0 to disable (rare — you probably don’t want a growing history at all, in which case make sure your tools have terminates_thread: true).

Set it in the binding’s params:

curl -X PATCH https://cloud.gosendapi.com/v1/agent-bindings/$BINDING_ID \
  -H "X-API-Key: $GOSENDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "wizardEnabled": false,
      "catchAllAction": "escalate",
      "capConversacion": 20,
      "inactiveResetDays": 2
    }
  }'

Or fill it in the portal’s Params textarea when creating/editing the binding.

Every automatic reset emits an AgentEvent:

• thread.messages_auto_reset — post-milestone (properties: milestone_tool, previous_message_count).
• thread.messages_inactivity_reset — inactivity (properties: previous_message_count, inactive_days, threshold_days, threshold_source).
• thread.messages_reset — manual (properties: previous_message_count, reset_by_user_id, reason).

Use these events for audit and to reason about token consumption on a tenant.

Ownership and errors

Every resource is scoped to the tenant behind the X-API-Key. Cross-tenant reads return 404 (not 403 — we don’t leak existence). Common conflicts:

Full error handling patterns: error handling guide.

Related

• AI Agents — Tools declaration — the five blocks + three namespaces + SSRF floor + pick allowlist
• AI Agents — LLM providers — provider registry, pricing snapshots, tool mapping per vendor, adding your own provider
• API Reference — interactive spec, every endpoint