Referencia de la API

Tact Platform API

Generada a partir del archivo OpenAPI del motor. Cada solicitud es JSON sobre HTTPS con la clave secreta del tenant.

115 rutasversión 2026-11-01

URL base
Marcador hasta que se elija el dominio.
https://api.tact.example
Autenticación
Envía la clave secreta del tenant como bearer token.
Authorization: Bearer tact_sk_live_...
Alcance de Account
Los recursos de Account llevan el id de la Account o tu propia referencia.
Tact-Account: ext:cust_4821
Idempotencia
Cada POST acepta una clave, válida por 24 horas.
Idempotency-Key: provision-cust_4821

Models2 rutas

GET/v1/models

List the Tact models (OpenAI compatible)

models:invoke

Ejemplo de respuesta · 200

{
  "object": "list",
  "data": [
    {
      "id": "tact-1",
      "object": "model",
      "created": 1,
      "owned_by": "tact",
      "description": "string"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/chat/completions

Chat completion (OpenAI compatible; stream with stream: true)

Same wire format as OpenAI chat completions: point the OpenAI SDK at this base URL with a key that has models:invoke. The orchestrator picks the provider per request inside the data lock of the tenant (region and health data). With stream: true the answer comes as server-sent events (chat.completion.chunk) ending with [DONE]. Idempotency-Key is ignored here.

models:invoke

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

modelobligatorio
"tact-1" | "tact-1-mini" | "tact-1-pro"
messagesobligatorio
object[]
tools
object[]
tool_choice
object
response_format
object
text, json_object or json_schema
max_tokens
integer
Default 1024, max 8192
max_completion_tokens
integer
Same as max_tokens
temperature
number
0 to 2 (values above 1 are sent as 1)
stop
object
stream
boolean
stream_options
object

Ejemplo de solicitud

{
  "model": "tact-1",
  "messages": [
    {
      "role": "system",
      "content": "string",
      "tool_calls": [
        {}
      ],
      "tool_call_id": "string"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "Harbour Physio",
        "description": "string",
        "parameters": {}
      }
    }
  ],
  "tool_choice": "auto",
  "response_format": {},
  "max_tokens": 1,
  "max_completion_tokens": 1,
  "temperature": 1.5,
  "stop": "string",
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

Ejemplo de respuesta · 200

{
  "id": "msg_9001",
  "object": "chat.completion",
  "created": 1,
  "model": "string",
  "choices": [
    {
      "index": 1,
      "message": {
        "role": "assistant",
        "content": "string",
        "tool_calls": [
          {}
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Tenant8 rutas

GET/v1/status

Component status (no authentication)

Sin autenticación

Ejemplo de respuesta · 200

{
  "object": "status",
  "status": "operational",
  "components": [
    {
      "name": "Harbour Physio",
      "state": "ok",
      "since": "2026-11-02T09:30:00+00:00"
    }
  ],
  "checked_at": "2026-11-02T09:30:00+00:00"
}

Errores · 429

429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/.well-known/jwks.json

Public keys of the Tact-Envelope sent on tool calls and outbox pulls (no authentication)

Sin autenticación

Ejemplo de respuesta · 200

{
  "keys": [
    {
      "kty": "string",
      "crv": "string",
      "x": "string",
      "y": "string",
      "alg": "string",
      "use": "string",
      "kid": "string"
    }
  ]
}

Errores · 429

429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/tenant

The authenticated tenant and key

Ejemplo de respuesta · 200

{
  "id": "ten_01JB6ZK8TQ0000000000000000",
  "object": "tenant",
  "slug": "string",
  "name": "Harbour Physio",
  "kind": "app",
  "status": "string",
  "default_data_region": "eu",
  "dpa_signed_at": "2026-11-02T09:30:00+00:00",
  "default_api_version": "string",
  "key": {
    "id": "key_01JB6ZK8TQ0000000000000000",
    "environment": "live",
    "scopes": [
      "accounts:read"
    ]
  },
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/tenant/readiness

Readiness checklist before going live

Ejemplo de respuesta · 200

{
  "object": "tenant_readiness",
  "mode": "live",
  "items": [
    {
      "key": "principal_verified",
      "status": "ok",
      "detail": "string"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/tenant/outbox_secret

Create or rotate the secret that signs pushes to ingress-tenant

The secret is shown once. Sign each push with Tact-Signature: t=<unix>,v1=hex(hmac_sha256(secret, t + "." + body)).

admin

Parámetros

Idempotency-Key
header · string

Ejemplo de respuesta · 201

{
  "object": "outbox_secret",
  "secret": "string",
  "push_url_path": "string",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/api_keys

List API keys

admin

Parámetros

limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "key_01JB6ZK8TQ0000000000000000",
      "object": "api_key",
      "environment": "live",
      "prefix": "string",
      "scopes": [
        "accounts:read"
      ],
      "expires_at": "2026-11-02T09:30:00+00:00",
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "last_used_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/api_keys

Create an API key (secret shown once)

admin

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

environmentobligatorio
"live" | "test"
scopesobligatorio
"accounts:read" | "accounts:write" | "knowledge:read" | "knowledge:write" | "contacts:read" | "contacts:write" | "threads:read" | "threads:write" | "goals:write" | "memory:read" | "memory:write" | "policies:read" | "policies:write" | "approvals:read" | "approvals:write" | "packs:read" | "packs:write" | "events:write" | "usage:read" | "models:invoke" | "privacy:write" | "admin"[]
expires_at
string (date-time)

Ejemplo de solicitud

{
  "environment": "live",
  "scopes": [
    "accounts:read"
  ],
  "expires_at": "2026-11-02T09:30:00+00:00"
}

Ejemplo de respuesta · 201

{
  "id": "key_01JB6ZK8TQ0000000000000000",
  "object": "api_key",
  "environment": "live",
  "prefix": "string",
  "scopes": [
    "accounts:read"
  ],
  "expires_at": "2026-11-02T09:30:00+00:00",
  "revoked_at": "2026-11-02T09:30:00+00:00",
  "last_used_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "secret": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/api_keys/{id}/revoke

Revoke an API key

admin

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "key_01JB6ZK8TQ0000000000000000",
  "object": "api_key",
  "environment": "live",
  "prefix": "string",
  "scopes": [
    "accounts:read"
  ],
  "expires_at": "2026-11-02T09:30:00+00:00",
  "revoked_at": "2026-11-02T09:30:00+00:00",
  "last_used_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Provisioning4 rutas

GET/v1/provisioning_template

Read the provisioning template

accounts:read

Ejemplo de respuesta · 200

{
  "pack": {
    "id": "msg_9001",
    "key": "principal_verified",
    "version": "string"
  },
  "tool_base_url": "string",
  "agent": {
    "persona": {
      "name_template": "string",
      "default_locale": "en-IE"
    },
    "modes": [
      "assistant"
    ]
  },
  "playbooks": {
    "key": "on"
  },
  "policy_overrides": [
    {
      "action_type": "string",
      "decision": "allow",
      "conditions": [
        {
          "fact": "appointment.hours_until_start",
          "op": "eq",
          "value": null
        }
      ]
    }
  ],
  "budget": {
    "monthly_usd_micros": 1,
    "alert_at": [
      1.5
    ],
    "on_exceed": "alert"
  },
  "data_region_rule": {
    "key": "eu"
  },
  "onboarding": {
    "required_steps": [
      "string"
    ],
    "optional_steps": [
      "string"
    ]
  },
  "knowledge_kinds_expected": [
    "profile"
  ],
  "prerequisites_ack": [
    "string"
  ],
  "events": {
    "mode": "push"
  },
  "verify_tool_server": true,
  "object": "provisioning_template",
  "version": 1,
  "tool_server_verified_at": "2026-11-02T09:30:00+00:00",
  "rollout": {},
  "updated_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PUT/v1/provisioning_template

Write the provisioning template every new account receives

The tool server must list the tools required by the acknowledged phases at GET {tool_base_url}/.well-known/tact-tools, or the call fails with 422 missing_prerequisite.

accounts:write

Cuerpo de la solicitud

packobligatorio
object
tool_base_urlobligatorio
string
https URL of the tenant tool server
agent
object
playbooks
object
policy_overrides
object[]
budget
object
data_region_rule
object
ISO country or 'default' to region
onboarding
object
knowledge_kinds_expected
"profile" | "location" | "hours" | "holiday" | "service" | "staff" | "price" | "insurance" | "policy" | "faq" | "tone" | "document"[]
prerequisites_ack
string[]
Pack phases the tenant implemented (S0, S1)
events
object
verify_tool_server
boolean
false only with a test key

Ejemplo de solicitud

{
  "pack": {
    "id": "msg_9001",
    "key": "principal_verified",
    "version": "string"
  },
  "tool_base_url": "string",
  "agent": {
    "persona": {
      "name_template": "string",
      "default_locale": "en-IE"
    },
    "modes": [
      "assistant"
    ]
  },
  "playbooks": {
    "key": "on"
  },
  "policy_overrides": [
    {
      "action_type": "string",
      "decision": "allow",
      "conditions": [
        {
          "fact": "appointment.hours_until_start",
          "op": "eq",
          "value": null
        }
      ]
    }
  ],
  "budget": {
    "monthly_usd_micros": 1,
    "alert_at": [
      1.5
    ],
    "on_exceed": "alert"
  },
  "data_region_rule": {
    "key": "eu"
  },
  "onboarding": {
    "required_steps": [
      "string"
    ],
    "optional_steps": [
      "string"
    ]
  },
  "knowledge_kinds_expected": [
    "profile"
  ],
  "prerequisites_ack": [
    "string"
  ],
  "events": {
    "mode": "push"
  },
  "verify_tool_server": true
}

Ejemplo de respuesta · 200

{
  "pack": {
    "id": "msg_9001",
    "key": "principal_verified",
    "version": "string"
  },
  "tool_base_url": "string",
  "agent": {
    "persona": {
      "name_template": "string",
      "default_locale": "en-IE"
    },
    "modes": [
      "assistant"
    ]
  },
  "playbooks": {
    "key": "on"
  },
  "policy_overrides": [
    {
      "action_type": "string",
      "decision": "allow",
      "conditions": [
        {
          "fact": "appointment.hours_until_start",
          "op": "eq",
          "value": null
        }
      ]
    }
  ],
  "budget": {
    "monthly_usd_micros": 1,
    "alert_at": [
      1.5
    ],
    "on_exceed": "alert"
  },
  "data_region_rule": {
    "key": "eu"
  },
  "onboarding": {
    "required_steps": [
      "string"
    ],
    "optional_steps": [
      "string"
    ]
  },
  "knowledge_kinds_expected": [
    "profile"
  ],
  "prerequisites_ack": [
    "string"
  ],
  "events": {
    "mode": "push"
  },
  "verify_tool_server": true,
  "object": "provisioning_template",
  "version": 1,
  "tool_server_verified_at": "2026-11-02T09:30:00+00:00",
  "rollout": {},
  "updated_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/provisioning_template/rollout

Roll the current template out to existing accounts (canary, then all after 48 h)

accounts:write

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

phase
"canary" | "all"
canary_percent
integer

Ejemplo de solicitud

{
  "phase": "canary",
  "canary_percent": 1
}

Ejemplo de respuesta · 200

{
  "object": "provisioning_rollout",
  "version": 1,
  "phase": "canary",
  "canary_percent": 1,
  "canary_started_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00",
  "accounts_updated": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/accounts/provision

Provision an account with its owner, agent, pack, policy, budget and onboarding (upsert by external_ref)

Returns 201 when the account is created and 200 when it already existed. Never creates a second agent.

accounts:write

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

external_refobligatorio
string
Account id in the tenant system
nameobligatorio
string
kind
"business" | "person"
countryobligatorio
string
ISO 3166-1 alpha-2; any country works when timezone, locale, currency and regime are sent
timezone
string
IANA time zone
locale
string
BCP 47
currency
string
ISO 4217
regime
string
Data protection regime (gdpr, lgpd, appi ...)
holds_health_data
boolean
ownerobligatorio
object
lawful_basis
object
Lawful basis per purpose (service, reminder, recall, marketing)

Ejemplo de solicitud

{
  "external_ref": "cust_4821",
  "name": "Harbour Physio",
  "kind": "business",
  "country": "IE",
  "timezone": "Europe/Dublin",
  "locale": "en-IE",
  "currency": "EUR",
  "regime": "gdpr",
  "holds_health_data": true,
  "owner": {
    "external_ref": "cust_4821",
    "display_name": "Niamh Byrne",
    "kind": "person",
    "role": "string",
    "channels": [
      {
        "channel": "whatsapp",
        "address": "+353871234567",
        "priority": 1
      }
    ],
    "approval_permissions": [
      "string"
    ],
    "locale": "en-IE",
    "timezone": "Europe/Dublin"
  },
  "lawful_basis": {
    "key": "string"
  }
}

Ejemplo de respuesta · 201

{
  "account": {
    "id": "acc_01JB6ZK8TQ0000000000000000",
    "object": "account",
    "external_ref": "cust_4821",
    "status": "string",
    "data_region": "eu"
  },
  "agent": {
    "id": "agt_01JB6ZK8TQ0000000000000000",
    "object": "agent",
    "status": "string",
    "persona": {
      "name": "Harbour Physio"
    },
    "pack": {
      "id": "pck_01JB6ZK8TQ0000000000000000",
      "key": "principal_verified",
      "version": "string"
    }
  },
  "owner_principal": {
    "id": "prn_01JB6ZK8TQ0000000000000000",
    "object": "principal",
    "channels_pending_verification": [
      "whatsapp"
    ]
  },
  "onboarding": {
    "steps": [
      {
        "key": "principal_verified",
        "done": true,
        "at": "2026-11-02T09:30:00+00:00",
        "optional": true
      }
    ]
  },
  "template_version": 1,
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Accounts7 rutas

GET/v1/accounts

List accounts

accounts:read

Parámetros

limit
query · integer
cursor
query · string
status
query · string
external_ref
query · string
created_after
query · string (date-time)

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "acc_01JB6ZK8TQ0000000000000000",
      "object": "account",
      "external_ref": "cust_4821",
      "name": "Harbour Physio",
      "kind": "string",
      "status": "onboarding",
      "country": "IE",
      "timezone": "Europe/Dublin",
      "locale": "en-IE",
      "currency": "EUR",
      "regime": "gdpr",
      "data_region": "eu",
      "holds_health_data": true,
      "quiet_hours": {
        "start": "20:00",
        "end": "09:00"
      },
      "lawful_basis": {},
      "limits": {},
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "onboarding": {
        "steps": [
          {
            "key": "principal_verified",
            "done": true,
            "at": "2026-11-02T09:30:00+00:00",
            "optional": true
          }
        ]
      },
      "template_version": 1,
      "paused_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/accounts/{id}

Retrieve an account

accounts:read

Parámetros

idobligatorio
path · string

Ejemplo de respuesta · 200

{
  "id": "acc_01JB6ZK8TQ0000000000000000",
  "object": "account",
  "external_ref": "cust_4821",
  "name": "Harbour Physio",
  "kind": "string",
  "status": "onboarding",
  "country": "IE",
  "timezone": "Europe/Dublin",
  "locale": "en-IE",
  "currency": "EUR",
  "regime": "gdpr",
  "data_region": "eu",
  "holds_health_data": true,
  "quiet_hours": {
    "start": "20:00",
    "end": "09:00"
  },
  "lawful_basis": {},
  "limits": {},
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "onboarding": {
    "steps": [
      {
        "key": "principal_verified",
        "done": true,
        "at": "2026-11-02T09:30:00+00:00",
        "optional": true
      }
    ]
  },
  "template_version": 1,
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/accounts/{id}

Update an account and mark onboarding steps done

accounts:write

Parámetros

idobligatorio
path · string

Cuerpo de la solicitud

name
string
locale
string
timezone
string
holds_health_data
boolean
quiet_hours
object
lawful_basis
object
onboarding
object
Steps done in the tenant product: disclosure_reviewed, playbooks_reviewed, account_taught, knowledge_synced

Ejemplo de solicitud

{
  "name": "Harbour Physio",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "holds_health_data": true,
  "quiet_hours": {
    "start": "20:00",
    "end": "09:00"
  },
  "lawful_basis": {
    "key": "string"
  },
  "onboarding": {
    "key": true
  }
}

Ejemplo de respuesta · 200

{
  "id": "acc_01JB6ZK8TQ0000000000000000",
  "object": "account",
  "external_ref": "cust_4821",
  "name": "Harbour Physio",
  "kind": "string",
  "status": "onboarding",
  "country": "IE",
  "timezone": "Europe/Dublin",
  "locale": "en-IE",
  "currency": "EUR",
  "regime": "gdpr",
  "data_region": "eu",
  "holds_health_data": true,
  "quiet_hours": {
    "start": "20:00",
    "end": "09:00"
  },
  "lawful_basis": {},
  "limits": {},
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "onboarding": {
    "steps": [
      {
        "key": "principal_verified",
        "done": true,
        "at": "2026-11-02T09:30:00+00:00",
        "optional": true
      }
    ]
  },
  "template_version": 1,
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/accounts/{id}/pause

Pause an account

accounts:write

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "acc_01JB6ZK8TQ0000000000000000",
  "object": "account",
  "external_ref": "cust_4821",
  "name": "Harbour Physio",
  "kind": "string",
  "status": "onboarding",
  "country": "IE",
  "timezone": "Europe/Dublin",
  "locale": "en-IE",
  "currency": "EUR",
  "regime": "gdpr",
  "data_region": "eu",
  "holds_health_data": true,
  "quiet_hours": {
    "start": "20:00",
    "end": "09:00"
  },
  "lawful_basis": {},
  "limits": {},
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "onboarding": {
    "steps": [
      {
        "key": "principal_verified",
        "done": true,
        "at": "2026-11-02T09:30:00+00:00",
        "optional": true
      }
    ]
  },
  "template_version": 1,
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/accounts/{id}/resume

Resume a paused account

accounts:write

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "acc_01JB6ZK8TQ0000000000000000",
  "object": "account",
  "external_ref": "cust_4821",
  "name": "Harbour Physio",
  "kind": "string",
  "status": "onboarding",
  "country": "IE",
  "timezone": "Europe/Dublin",
  "locale": "en-IE",
  "currency": "EUR",
  "regime": "gdpr",
  "data_region": "eu",
  "holds_health_data": true,
  "quiet_hours": {
    "start": "20:00",
    "end": "09:00"
  },
  "lawful_basis": {},
  "limits": {},
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "onboarding": {
    "steps": [
      {
        "key": "principal_verified",
        "done": true,
        "at": "2026-11-02T09:30:00+00:00",
        "optional": true
      }
    ]
  },
  "template_version": 1,
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/accounts/{id}/close

Close an account and schedule the cascade erasure

accounts:write

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Cuerpo de la solicitud

retention_days
integer
reason
string

Ejemplo de solicitud

{
  "retention_days": 0,
  "reason": "requested by the account"
}

Ejemplo de respuesta · 200

{
  "account": {
    "id": "acc_01JB6ZK8TQ0000000000000000",
    "object": "account",
    "external_ref": "cust_4821",
    "name": "Harbour Physio",
    "kind": "string",
    "status": "onboarding",
    "country": "IE",
    "timezone": "Europe/Dublin",
    "locale": "en-IE",
    "currency": "EUR",
    "regime": "gdpr",
    "data_region": "eu",
    "holds_health_data": true,
    "quiet_hours": {
      "start": "20:00",
      "end": "09:00"
    },
    "lawful_basis": {},
    "limits": {},
    "agent_id": "agt_01JB6ZK8TQ0000000000000000",
    "onboarding": {
      "steps": [
        {
          "key": "principal_verified",
          "done": true,
          "at": "2026-11-02T09:30:00+00:00",
          "optional": true
        }
      ]
    },
    "template_version": 1,
    "paused_at": "2026-11-02T09:30:00+00:00",
    "created_at": "2026-11-02T09:30:00+00:00"
  },
  "erasure_request_id": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/account_sessions

Create a 15 minute session token for Tact Elements

Tact-Account obligatorioaccounts:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

principal_idobligatorio
string
componentsobligatorio
"tact-onboarding" | "tact-thread" | "tact-approvals" | "tact-knowledge" | "tact-policies" | "tact-usage" | "whatsapp-connect"[]
step_up
boolean

Ejemplo de solicitud

{
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "components": [
    "tact-onboarding"
  ],
  "step_up": true
}

Ejemplo de respuesta · 201

{
  "id": "ses_01JB6ZK8TQ0000000000000000",
  "object": "account_session",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "components": [
    "string"
  ],
  "step_up": true,
  "token": "string",
  "expires_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Principals6 rutas

GET/v1/principals

List principals

Tact-Account obligatorioaccounts:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "prn_01JB6ZK8TQ0000000000000000",
      "object": "principal",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "kind": "person",
      "role": "string",
      "display_name": "Niamh Byrne",
      "external_ref": "cust_4821",
      "locale": "en-IE",
      "timezone": "Europe/Dublin",
      "approval_permissions": [
        "string"
      ],
      "channels": [
        {
          "id": "pch_01JB6ZK8TQ0000000000000000",
          "object": "principal_channel",
          "channel": "whatsapp",
          "address": "+353871234567",
          "priority": 1,
          "verified_at": "2026-11-02T09:30:00+00:00"
        }
      ],
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/principals

Create or update a principal (upsert by external_ref)

Tact-Account obligatorioaccounts:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

kind
"person" | "organization" | "entity"
role
"owner" | "admin" | "staff" | "entity" | "reception" | "technical_lead"
display_nameobligatorio
string
external_ref
string
approval_permissions
string[]
channels
object[]
locale
string
timezone
string

Ejemplo de solicitud

{
  "kind": "person",
  "role": "owner",
  "display_name": "Niamh Byrne",
  "external_ref": "cust_4821",
  "approval_permissions": [
    "string"
  ],
  "channels": [
    {
      "channel": "whatsapp",
      "address": "+353871234567",
      "priority": 1
    }
  ],
  "locale": "en-IE",
  "timezone": "Europe/Dublin"
}

Ejemplo de respuesta · 201

{
  "id": "prn_01JB6ZK8TQ0000000000000000",
  "object": "principal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "kind": "person",
  "role": "string",
  "display_name": "Niamh Byrne",
  "external_ref": "cust_4821",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "approval_permissions": [
    "string"
  ],
  "channels": [
    {
      "id": "pch_01JB6ZK8TQ0000000000000000",
      "object": "principal_channel",
      "channel": "whatsapp",
      "address": "+353871234567",
      "priority": 1,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/principals/{id}

Retrieve a principal

Tact-Account opcionalaccounts:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "prn_01JB6ZK8TQ0000000000000000",
  "object": "principal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "kind": "person",
  "role": "string",
  "display_name": "Niamh Byrne",
  "external_ref": "cust_4821",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "approval_permissions": [
    "string"
  ],
  "channels": [
    {
      "id": "pch_01JB6ZK8TQ0000000000000000",
      "object": "principal_channel",
      "channel": "whatsapp",
      "address": "+353871234567",
      "priority": 1,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/principals/{id}

Update a principal

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

display_name
string
role
string
approval_permissions
string[]
locale
string
timezone
string

Ejemplo de solicitud

{
  "display_name": "Niamh Byrne",
  "role": "string",
  "approval_permissions": [
    "string"
  ],
  "locale": "en-IE",
  "timezone": "Europe/Dublin"
}

Ejemplo de respuesta · 200

{
  "id": "prn_01JB6ZK8TQ0000000000000000",
  "object": "principal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "kind": "person",
  "role": "string",
  "display_name": "Niamh Byrne",
  "external_ref": "cust_4821",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "approval_permissions": [
    "string"
  ],
  "channels": [
    {
      "id": "pch_01JB6ZK8TQ0000000000000000",
      "object": "principal_channel",
      "channel": "whatsapp",
      "address": "+353871234567",
      "priority": 1,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/principals/{id}/channels

Add a channel to a principal and send a verification code

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

channelobligatorio
"whatsapp" | "sms" | "email" | "voice" | "telegram" | "in_app" | "imessage"
addressobligatorio
string
E.164 for phones, e-mail address, or the tenant user id for in_app
priority
integer

Ejemplo de solicitud

{
  "channel": "whatsapp",
  "address": "+353871234567",
  "priority": 1
}

Ejemplo de respuesta · 201

{
  "id": "pch_01JB6ZK8TQ0000000000000000",
  "object": "principal_channel",
  "channel": "whatsapp",
  "address": "+353871234567",
  "priority": 1,
  "verified_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/principals/{id}/channels/{cid}/verify

Verify a principal channel with the 6 digit code (without code: resend it)

With a test key nothing is sent and the code is always 000000.

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
cidobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

code
string

Ejemplo de solicitud

{
  "code": "482913"
}

Ejemplo de respuesta · 200

{
  "id": "pch_01JB6ZK8TQ0000000000000000",
  "object": "principal_channel",
  "channel": "whatsapp",
  "address": "+353871234567",
  "priority": 1,
  "verified_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Agent5 rutas

GET/v1/agent

The agent of the account in Tact-Account

Tact-Account obligatorioaccounts:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>

Ejemplo de respuesta · 200

{
  "id": "agt_01JB6ZK8TQ0000000000000000",
  "object": "agent",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "status": "onboarding",
  "modes": [
    "assistant"
  ],
  "name": "Harbour Physio",
  "persona": {},
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "model_profile": "string",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string"
  },
  "pack_install_id": "pin_01JB6ZK8TQ0000000000000000",
  "playbooks": {
    "key": "on"
  },
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/agents/{id}

Retrieve an agent

Tact-Account opcionalaccounts:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "agt_01JB6ZK8TQ0000000000000000",
  "object": "agent",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "status": "onboarding",
  "modes": [
    "assistant"
  ],
  "name": "Harbour Physio",
  "persona": {},
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "model_profile": "string",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string"
  },
  "pack_install_id": "pin_01JB6ZK8TQ0000000000000000",
  "playbooks": {
    "key": "on"
  },
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/agents/{id}

Update persona, channels and overrides

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

channel_ids
string[]
modes
"assistant" | "representative"[]
persona
object
overrides
object

Ejemplo de solicitud

{
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "modes": [
    "assistant"
  ],
  "persona": {
    "name": "Harbour Physio",
    "default_locale": "en-IE",
    "signature": "string"
  },
  "overrides": {
    "key": 1.5
  }
}

Ejemplo de respuesta · 200

{
  "id": "agt_01JB6ZK8TQ0000000000000000",
  "object": "agent",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "status": "onboarding",
  "modes": [
    "assistant"
  ],
  "name": "Harbour Physio",
  "persona": {},
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "model_profile": "string",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string"
  },
  "pack_install_id": "pin_01JB6ZK8TQ0000000000000000",
  "playbooks": {
    "key": "on"
  },
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/agents/{id}/pause

Pause the agent

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "agt_01JB6ZK8TQ0000000000000000",
  "object": "agent",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "status": "onboarding",
  "modes": [
    "assistant"
  ],
  "name": "Harbour Physio",
  "persona": {},
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "model_profile": "string",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string"
  },
  "pack_install_id": "pin_01JB6ZK8TQ0000000000000000",
  "playbooks": {
    "key": "on"
  },
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/agents/{id}/resume

Resume the agent

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "agt_01JB6ZK8TQ0000000000000000",
  "object": "agent",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "status": "onboarding",
  "modes": [
    "assistant"
  ],
  "name": "Harbour Physio",
  "persona": {},
  "channel_ids": [
    "chn_01JB6ZK8TQ0000000000000000"
  ],
  "model_profile": "string",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string"
  },
  "pack_install_id": "pin_01JB6ZK8TQ0000000000000000",
  "playbooks": {
    "key": "on"
  },
  "paused_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Channels5 rutas

POST/v1/channels/whatsapp/signup_sessions

Start a WhatsApp Embedded Signup for the account

Tact-Account obligatorioaccounts:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

return_urlobligatorio
string
https URL
coexistence_allowed
boolean
display_name_hint
string

Ejemplo de solicitud

{
  "return_url": "https://example.com/settings?tact=whatsapp",
  "coexistence_allowed": true,
  "display_name_hint": "string"
}

Ejemplo de respuesta · 201

{
  "id": "wss_01JB6ZK8TQ0000000000000000",
  "object": "whatsapp_signup_session",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "status": "open",
  "return_url": "https://example.com/settings?tact=whatsapp",
  "coexistence_allowed": true,
  "channel_id": "string",
  "error_code": "string",
  "expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00",
  "launch": {
    "app_id": "string",
    "config_id": "string",
    "state": "string",
    "extras": {}
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/channels/whatsapp/signup_sessions/{id}/complete

Finish the Embedded Signup with the code returned by Meta

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

codeobligatorio
string
Code returned by Meta
stateobligatorio
string
messaging_account_idobligatorio
string
phone_number_idobligatorio
string

Ejemplo de solicitud

{
  "code": "482913",
  "state": "string",
  "messaging_account_id": "string",
  "phone_number_id": "string"
}

Ejemplo de respuesta · 200

{
  "id": "wss_01JB6ZK8TQ0000000000000000",
  "object": "whatsapp_signup_session",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "status": "open",
  "return_url": "https://example.com/settings?tact=whatsapp",
  "coexistence_allowed": true,
  "channel_id": "string",
  "error_code": "string",
  "expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00",
  "channel": {
    "id": "chn_01JB6ZK8TQ0000000000000000",
    "object": "channel",
    "account_id": "acc_01JB6ZK8TQ0000000000000000",
    "channel": "whatsapp",
    "provider": "string",
    "address": "+353871234567",
    "status": "pending",
    "shared": true,
    "coexistence": true,
    "messaging_account_id": "string",
    "phone_number_id": "string",
    "created_at": "2026-11-02T09:30:00+00:00"
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/channels

List the account channels

Tact-Account obligatorioaccounts:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
channel
query · "whatsapp" | "sms" | "email" | "voice" | "telegram" | "in_app" | "imessage"

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "chn_01JB6ZK8TQ0000000000000000",
      "object": "channel",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "channel": "whatsapp",
      "provider": "string",
      "address": "+353871234567",
      "status": "pending",
      "shared": true,
      "coexistence": true,
      "messaging_account_id": "string",
      "phone_number_id": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/channels/{id}/templates

List channel templates

Tact-Account opcionalaccounts:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "tpl_01JB6ZK8TQ0000000000000000",
      "object": "channel_template",
      "channel_id": "chn_01JB6ZK8TQ0000000000000000",
      "name": "Harbour Physio",
      "locale": "en-IE",
      "category": "utility",
      "status": "string",
      "variables": [
        null
      ]
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/channels/{id}/templates/sync

Submit the pack templates to Meta for this channel

Tact-Account opcionalaccounts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 202

{
  "object": "templates_sync",
  "channel_id": "chn_01JB6ZK8TQ0000000000000000",
  "status": "queued",
  "job_id": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Knowledge10 rutas

GET/v1/knowledge

List knowledge items

Tact-Account obligatorioknowledge:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
kind
query · string
include_deleted
query · boolean

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "kni_01JB6ZK8TQ0000000000000000",
      "object": "knowledge_item",
      "kind": "profile",
      "external_ref": "cust_4821",
      "data": {},
      "visibility": "all",
      "authority": "tenant_system",
      "source_updated_at": "2026-11-02T09:30:00+00:00",
      "content_sha256": "string",
      "confirmed_by": "string",
      "deleted": true,
      "deleted_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "updated_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PUT/v1/knowledge/{kind}/{ref}

Write one knowledge item

Tact-Account obligatorioknowledge:write

Parámetros

kindobligatorio
path · string
refobligatorio
path · string
Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>

Cuerpo de la solicitud

source_updated_atobligatorio
string (date-time)
Version in the tenant system; older writes are ignored
dataobligatorio
object
Validated by the pack schema of the kind
visibility
"all" | "assistant_only"

Ejemplo de solicitud

{
  "source_updated_at": "2026-11-02T09:30:00+00:00",
  "data": {},
  "visibility": "all"
}

Ejemplo de respuesta · 200

{
  "id": "kni_01JB6ZK8TQ0000000000000000",
  "object": "knowledge_item",
  "kind": "profile",
  "external_ref": "cust_4821",
  "data": {},
  "visibility": "all",
  "authority": "tenant_system",
  "source_updated_at": "2026-11-02T09:30:00+00:00",
  "content_sha256": "string",
  "confirmed_by": "string",
  "deleted": true,
  "deleted_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "updated_at": "2026-11-02T09:30:00+00:00",
  "result": "upserted",
  "knowledge_version": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

DELETE/v1/knowledge/{kind}/{ref}

Tombstone one knowledge item

Tact-Account obligatorioknowledge:write

Parámetros

kindobligatorio
path · string
refobligatorio
path · string
Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>

Ejemplo de respuesta · 200

{
  "object": "knowledge_item",
  "kind": "profile",
  "external_ref": "cust_4821",
  "deleted": true,
  "knowledge_version": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/knowledge/syncs

Snapshot or delta sync (up to 1,000 items per call; parts for bigger snapshots)

In snapshot mode, items of the listed kinds that did not arrive become tombstones once the last part arrives.

Tact-Account obligatorioknowledge:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

modeobligatorio
"snapshot" | "delta"
kinds
"profile" | "location" | "hours" | "holiday" | "service" | "staff" | "price" | "insurance" | "policy" | "faq" | "tone" | "document"[]
sync_ref
string
Tenant id of the sync; required with parts
part
integer
total_parts
integer
items
object[]
deletes
object[]

Ejemplo de solicitud

{
  "mode": "snapshot",
  "kinds": [
    "profile"
  ],
  "sync_ref": "string",
  "part": 1,
  "total_parts": 1,
  "items": [
    {
      "kind": "profile",
      "external_ref": "cust_4821",
      "source_updated_at": "2026-11-02T09:30:00+00:00",
      "data": {},
      "visibility": "all"
    }
  ],
  "deletes": [
    {
      "kind": "profile",
      "external_ref": "cust_4821"
    }
  ]
}

Ejemplo de respuesta · 202

{
  "id": "ksy_01JB6ZK8TQ0000000000000000",
  "object": "knowledge_sync",
  "mode": "string",
  "kinds": [
    "profile"
  ],
  "sync_ref": "string",
  "status": "processing",
  "parts_expected": 1,
  "parts_received": 1,
  "counts": {},
  "knowledge_version": 1,
  "started_at": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00",
  "sync_id": "ksy_01JB6ZK8TQ0000000000000000",
  "rejected": [
    {
      "index": 1,
      "external_ref": "cust_4821",
      "code": "482913",
      "param": "string",
      "message": "Contact has no active consent for purpose 'recall' on channel 'whatsapp'."
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/knowledge/syncs/{id}

Retrieve a sync

Tact-Account opcionalknowledge:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "ksy_01JB6ZK8TQ0000000000000000",
  "object": "knowledge_sync",
  "mode": "string",
  "kinds": [
    "profile"
  ],
  "sync_ref": "string",
  "status": "processing",
  "parts_expected": 1,
  "parts_received": 1,
  "counts": {},
  "knowledge_version": 1,
  "started_at": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/knowledge/digest

Digest per kind for the daily reconciliation

sha256 of the lines `external_ref TAB content_sha256 LF`, sorted by external_ref in byte order.

Tact-Account obligatorioknowledge:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>

Ejemplo de respuesta · 200

{
  "object": "knowledge_digest",
  "algorithm": "string",
  "knowledge_version": 1,
  "kinds": {
    "key": {
      "count": 1,
      "sha256": "string"
    }
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/knowledge/teach

Teach the agent (free text or structured proposals)

Tact-Account obligatorioknowledge:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

principal_idobligatorio
string
text
string
kind
"profile" | "location" | "hours" | "holiday" | "service" | "staff" | "price" | "insurance" | "policy" | "faq" | "tone" | "document"
proposals
object[]

Ejemplo de solicitud

{
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "text": "Can I move Thursday to Friday?",
  "kind": "profile",
  "proposals": [
    {
      "kind": "profile",
      "data": {},
      "summary": {},
      "external_ref": "cust_4821"
    }
  ]
}

Ejemplo de respuesta · 202

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "kpr_01JB6ZK8TQ0000000000000000",
      "object": "knowledge_proposal",
      "kind": "string",
      "proposed_data": {},
      "summary": {},
      "source": "string",
      "status": "pending",
      "conflict_with": "string",
      "decided_by": "string",
      "decided_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "item": {
        "id": "kni_01JB6ZK8TQ0000000000000000",
        "object": "knowledge_item",
        "kind": "profile",
        "external_ref": "cust_4821",
        "data": {},
        "visibility": "all",
        "authority": "tenant_system",
        "source_updated_at": "2026-11-02T09:30:00+00:00",
        "content_sha256": "string",
        "confirmed_by": "string",
        "deleted": true,
        "deleted_at": "2026-11-02T09:30:00+00:00",
        "created_at": "2026-11-02T09:30:00+00:00",
        "updated_at": "2026-11-02T09:30:00+00:00"
      }
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/knowledge/proposals

List knowledge proposals

Tact-Account obligatorioknowledge:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "kpr_01JB6ZK8TQ0000000000000000",
      "object": "knowledge_proposal",
      "kind": "string",
      "proposed_data": {},
      "summary": {},
      "source": "string",
      "status": "pending",
      "conflict_with": "string",
      "decided_by": "string",
      "decided_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "item": {
        "id": "kni_01JB6ZK8TQ0000000000000000",
        "object": "knowledge_item",
        "kind": "profile",
        "external_ref": "cust_4821",
        "data": {},
        "visibility": "all",
        "authority": "tenant_system",
        "source_updated_at": "2026-11-02T09:30:00+00:00",
        "content_sha256": "string",
        "confirmed_by": "string",
        "deleted": true,
        "deleted_at": "2026-11-02T09:30:00+00:00",
        "created_at": "2026-11-02T09:30:00+00:00",
        "updated_at": "2026-11-02T09:30:00+00:00"
      }
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/knowledge/proposals/{id}/confirm

Confirm a proposal (conflicts with tenant data are reported)

Tact-Account opcionalknowledge:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

principal_idobligatorio
string
data
object
Overrides the proposed data
external_ref
string

Ejemplo de solicitud

{
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "data": {},
  "external_ref": "cust_4821"
}

Ejemplo de respuesta · 200

{
  "id": "kpr_01JB6ZK8TQ0000000000000000",
  "object": "knowledge_proposal",
  "kind": "string",
  "proposed_data": {},
  "summary": {},
  "source": "string",
  "status": "pending",
  "conflict_with": "string",
  "decided_by": "string",
  "decided_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "item": {
    "id": "kni_01JB6ZK8TQ0000000000000000",
    "object": "knowledge_item",
    "kind": "profile",
    "external_ref": "cust_4821",
    "data": {},
    "visibility": "all",
    "authority": "tenant_system",
    "source_updated_at": "2026-11-02T09:30:00+00:00",
    "content_sha256": "string",
    "confirmed_by": "string",
    "deleted": true,
    "deleted_at": "2026-11-02T09:30:00+00:00",
    "created_at": "2026-11-02T09:30:00+00:00",
    "updated_at": "2026-11-02T09:30:00+00:00"
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/knowledge/proposals/{id}/reject

Reject a proposal

Tact-Account opcionalknowledge:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

principal_idobligatorio
string

Ejemplo de solicitud

{
  "principal_id": "prn_01JB6ZK8TQ0000000000000000"
}

Ejemplo de respuesta · 200

{
  "id": "kpr_01JB6ZK8TQ0000000000000000",
  "object": "knowledge_proposal",
  "kind": "string",
  "proposed_data": {},
  "summary": {},
  "source": "string",
  "status": "pending",
  "conflict_with": "string",
  "decided_by": "string",
  "decided_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "item": {
    "id": "kni_01JB6ZK8TQ0000000000000000",
    "object": "knowledge_item",
    "kind": "profile",
    "external_ref": "cust_4821",
    "data": {},
    "visibility": "all",
    "authority": "tenant_system",
    "source_updated_at": "2026-11-02T09:30:00+00:00",
    "content_sha256": "string",
    "confirmed_by": "string",
    "deleted": true,
    "deleted_at": "2026-11-02T09:30:00+00:00",
    "created_at": "2026-11-02T09:30:00+00:00",
    "updated_at": "2026-11-02T09:30:00+00:00"
  }
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Contacts9 rutas

GET/v1/contacts

List contacts

Tact-Account obligatoriocontacts:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
external_ref
query · string
created_after
query · string (date-time)

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "con_01JB6ZK8TQ0000000000000000",
      "object": "contact",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "external_ref": "cust_4821",
      "kind": "string",
      "display_name": "Niamh Byrne",
      "locale": "en-IE",
      "timezone": "Europe/Dublin",
      "country": "IE",
      "is_minor": true,
      "guardian_contact_id": "string",
      "identity_level": "string",
      "do_not_contact": true,
      "channels": [
        {
          "id": "cch_01JB6ZK8TQ0000000000000000",
          "channel": "whatsapp",
          "address": "+353871234567",
          "is_preferred": true,
          "verified_at": "2026-11-02T09:30:00+00:00"
        }
      ],
      "consents": [
        {
          "id": "cst_01JB6ZK8TQ0000000000000000",
          "object": "consent",
          "contact_id": "con_01JB6ZK8TQ0000000000000000",
          "purpose": "string",
          "channel": "string",
          "lawful_basis": "string",
          "granted_at": "2026-11-02T09:30:00+00:00",
          "source": "string",
          "evidence": {},
          "revoked_at": "2026-11-02T09:30:00+00:00",
          "revoked_via": "string",
          "created_at": "2026-11-02T09:30:00+00:00"
        }
      ],
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/contacts

Create or update a contact (upsert by external_ref or channel address)

Tact-Account obligatoriocontacts:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

external_ref
string
display_name
string
kind
"person" | "organization" | "agent"
locale
string
timezone
string
country
string
is_minor
boolean
guardian_contact_id
string
channels
object[]
consents
object[]

Ejemplo de solicitud

{
  "external_ref": "cust_4821",
  "display_name": "Niamh Byrne",
  "kind": "person",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "con_01JB6ZK8TQ0000000000000000",
  "channels": [
    {
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true
    }
  ],
  "consents": [
    {
      "purpose": "reminder",
      "channel": "whatsapp",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "lawful_basis": "string"
    }
  ]
}

Ejemplo de respuesta · 201

{
  "id": "con_01JB6ZK8TQ0000000000000000",
  "object": "contact",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "external_ref": "cust_4821",
  "kind": "string",
  "display_name": "Niamh Byrne",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "string",
  "identity_level": "string",
  "do_not_contact": true,
  "channels": [
    {
      "id": "cch_01JB6ZK8TQ0000000000000000",
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "consents": [
    {
      "id": "cst_01JB6ZK8TQ0000000000000000",
      "object": "consent",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "purpose": "string",
      "channel": "string",
      "lawful_basis": "string",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "revoked_via": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/contacts/batch

Upsert up to 500 contacts

Tact-Account obligatoriocontacts:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

contactsobligatorio
object[]

Ejemplo de solicitud

{
  "contacts": [
    {
      "external_ref": "cust_4821",
      "display_name": "Niamh Byrne",
      "kind": "person",
      "locale": "en-IE",
      "timezone": "Europe/Dublin",
      "country": "IE",
      "is_minor": true,
      "guardian_contact_id": "con_01JB6ZK8TQ0000000000000000",
      "channels": [
        {
          "channel": "whatsapp",
          "address": "+353871234567",
          "is_preferred": true
        }
      ],
      "consents": [
        {
          "purpose": "reminder",
          "channel": "whatsapp",
          "granted_at": "2026-11-02T09:30:00+00:00",
          "source": "string",
          "evidence": {},
          "lawful_basis": "string"
        }
      ]
    }
  ]
}

Ejemplo de respuesta · 200

{
  "object": "contact_batch",
  "results": [
    {
      "index": 1,
      "status": "created",
      "id": "con_01JB6ZK8TQ0000000000000000",
      "external_ref": "cust_4821",
      "error": {}
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/contacts/{id}

Retrieve a contact

Tact-Account opcionalcontacts:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "con_01JB6ZK8TQ0000000000000000",
  "object": "contact",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "external_ref": "cust_4821",
  "kind": "string",
  "display_name": "Niamh Byrne",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "string",
  "identity_level": "string",
  "do_not_contact": true,
  "channels": [
    {
      "id": "cch_01JB6ZK8TQ0000000000000000",
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "consents": [
    {
      "id": "cst_01JB6ZK8TQ0000000000000000",
      "object": "consent",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "purpose": "string",
      "channel": "string",
      "lawful_basis": "string",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "revoked_via": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/contacts/{id}

Update a contact

Tact-Account opcionalcontacts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

external_ref
string
display_name
string
kind
"person" | "organization" | "agent"
locale
string
timezone
string
country
string
is_minor
boolean
guardian_contact_id
string
channels
object[]
consents
object[]

Ejemplo de solicitud

{
  "external_ref": "cust_4821",
  "display_name": "Niamh Byrne",
  "kind": "person",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "con_01JB6ZK8TQ0000000000000000",
  "channels": [
    {
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true
    }
  ],
  "consents": [
    {
      "purpose": "reminder",
      "channel": "whatsapp",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "lawful_basis": "string"
    }
  ]
}

Ejemplo de respuesta · 200

{
  "id": "con_01JB6ZK8TQ0000000000000000",
  "object": "contact",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "external_ref": "cust_4821",
  "kind": "string",
  "display_name": "Niamh Byrne",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "string",
  "identity_level": "string",
  "do_not_contact": true,
  "channels": [
    {
      "id": "cch_01JB6ZK8TQ0000000000000000",
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "consents": [
    {
      "id": "cst_01JB6ZK8TQ0000000000000000",
      "object": "consent",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "purpose": "string",
      "channel": "string",
      "lawful_basis": "string",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "revoked_via": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/contacts/{id}/do_not_contact

Block proactive contact (survives contact erasure)

Tact-Account opcionalcontacts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

channel
"whatsapp" | "sms" | "email" | "voice" | "whatsapp_call" | "imessage" | "any"
reason
"opt_out" | "complaint" | "legal"

Ejemplo de solicitud

{
  "channel": "whatsapp",
  "reason": "opt_out"
}

Ejemplo de respuesta · 200

{
  "id": "con_01JB6ZK8TQ0000000000000000",
  "object": "contact",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "external_ref": "cust_4821",
  "kind": "string",
  "display_name": "Niamh Byrne",
  "locale": "en-IE",
  "timezone": "Europe/Dublin",
  "country": "IE",
  "is_minor": true,
  "guardian_contact_id": "string",
  "identity_level": "string",
  "do_not_contact": true,
  "channels": [
    {
      "id": "cch_01JB6ZK8TQ0000000000000000",
      "channel": "whatsapp",
      "address": "+353871234567",
      "is_preferred": true,
      "verified_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "consents": [
    {
      "id": "cst_01JB6ZK8TQ0000000000000000",
      "object": "consent",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "purpose": "string",
      "channel": "string",
      "lawful_basis": "string",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "revoked_via": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/contacts/{id}/consents

List consents

Tact-Account opcionalcontacts:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "cst_01JB6ZK8TQ0000000000000000",
      "object": "consent",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "purpose": "string",
      "channel": "string",
      "lawful_basis": "string",
      "granted_at": "2026-11-02T09:30:00+00:00",
      "source": "string",
      "evidence": {},
      "revoked_at": "2026-11-02T09:30:00+00:00",
      "revoked_via": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/contacts/{id}/consents

Record a consent

Tact-Account opcionalcontacts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

purposeobligatorio
"reminder" | "recall" | "followup" | "marketing" | "recording" | "automated_call"
channelobligatorio
"whatsapp" | "sms" | "email" | "voice" | "whatsapp_call" | "any"
granted_atobligatorio
string (date-time)
source
string
evidence
object
lawful_basis
string
Defaults to the account lawful basis for the purpose

Ejemplo de solicitud

{
  "purpose": "reminder",
  "channel": "whatsapp",
  "granted_at": "2026-11-02T09:30:00+00:00",
  "source": "string",
  "evidence": {},
  "lawful_basis": "string"
}

Ejemplo de respuesta · 201

{
  "id": "cst_01JB6ZK8TQ0000000000000000",
  "object": "consent",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "purpose": "string",
  "channel": "string",
  "lawful_basis": "string",
  "granted_at": "2026-11-02T09:30:00+00:00",
  "source": "string",
  "evidence": {},
  "revoked_at": "2026-11-02T09:30:00+00:00",
  "revoked_via": "string",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/consents/{id}/revoke

Revoke a consent

Tact-Account opcionalcontacts:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

via
string

Ejemplo de solicitud

{
  "via": "string"
}

Ejemplo de respuesta · 200

{
  "id": "cst_01JB6ZK8TQ0000000000000000",
  "object": "consent",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "purpose": "string",
  "channel": "string",
  "lawful_basis": "string",
  "granted_at": "2026-11-02T09:30:00+00:00",
  "source": "string",
  "evidence": {},
  "revoked_at": "2026-11-02T09:30:00+00:00",
  "revoked_via": "string",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Privacy4 rutas

GET/v1/contacts/{id}/export

Export everything held about a contact

Tact-Account opcionalprivacy:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "object": "contact_export",
  "generated_at": "2026-11-02T09:30:00+00:00",
  "contact": {
    "id": "con_01JB6ZK8TQ0000000000000000",
    "object": "contact",
    "account_id": "acc_01JB6ZK8TQ0000000000000000",
    "external_ref": "cust_4821",
    "kind": "string",
    "display_name": "Niamh Byrne",
    "locale": "en-IE",
    "timezone": "Europe/Dublin",
    "country": "IE",
    "is_minor": true,
    "guardian_contact_id": "string",
    "identity_level": "string",
    "do_not_contact": true,
    "channels": [
      {
        "id": "cch_01JB6ZK8TQ0000000000000000",
        "channel": "whatsapp",
        "address": "+353871234567",
        "is_preferred": true,
        "verified_at": "2026-11-02T09:30:00+00:00"
      }
    ],
    "consents": [
      {
        "id": "cst_01JB6ZK8TQ0000000000000000",
        "object": "consent",
        "contact_id": "con_01JB6ZK8TQ0000000000000000",
        "purpose": "string",
        "channel": "string",
        "lawful_basis": "string",
        "granted_at": "2026-11-02T09:30:00+00:00",
        "source": "string",
        "evidence": {},
        "revoked_at": "2026-11-02T09:30:00+00:00",
        "revoked_via": "string",
        "created_at": "2026-11-02T09:30:00+00:00"
      }
    ],
    "created_at": "2026-11-02T09:30:00+00:00"
  },
  "threads": [
    {
      "id": "thr_01JB6ZK8TQ0000000000000000",
      "object": "thread",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "mode": "assistant",
      "status": "open",
      "channels": [
        "whatsapp"
      ],
      "window_open_until": "2026-11-02T09:30:00+00:00",
      "disclosed_at": "2026-11-02T09:30:00+00:00",
      "last_inbound_at": "2026-11-02T09:30:00+00:00",
      "last_outbound_at": "2026-11-02T09:30:00+00:00",
      "last_message_at": "2026-11-02T09:30:00+00:00",
      "open_goals": [
        {
          "id": "gol_01JB6ZK8TQ0000000000000000",
          "kind": "string",
          "status": "string"
        }
      ],
      "contact": {},
      "agent": {},
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "messages": [
    {
      "id": "msg_01JB6ZK8TQ0000000000000000",
      "object": "message",
      "thread_id": "thr_01JB6ZK8TQ0000000000000000",
      "direction": "in",
      "author": "string",
      "channel": "whatsapp",
      "kind": "string",
      "text": "Can I move Thursday to Friday?",
      "provider_message_id": "string",
      "proactive": true,
      "generated_by_ai": true,
      "delivery_status": "string",
      "run_id": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "messages_truncated": true,
  "memories": [
    {
      "id": "mem_01JB6ZK8TQ0000000000000000",
      "object": "memory",
      "subject": {
        "type": "contact",
        "id": "msg_9001"
      },
      "kind": "string",
      "content": "string",
      "origin": "string",
      "trust": "low",
      "confidence": 1.5,
      "sensitivity": "string",
      "valid_from": "2026-11-02T09:30:00+00:00",
      "valid_until": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "result": "string"
    }
  ],
  "actions": [
    {
      "id": "act_01JB6ZK8TQ0000000000000000",
      "object": "action",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "run_id": "string",
      "thread_id": "string",
      "action_type": "string",
      "tool": "string",
      "action_class": "string",
      "risk": "string",
      "status": "string",
      "policy_decision": "allow",
      "guardian_verdict": "string",
      "approval_id": "string",
      "target_contact_id": "string",
      "args_sha256": "string",
      "generated_by_ai": true,
      "result_summary": {},
      "cost_micros": 1,
      "seq": 1,
      "row_hash": "string",
      "created_at": "2026-11-02T09:30:00+00:00",
      "executed_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

DELETE/v1/contacts/{id}/data

Request the cascade erasure of a contact

Tact-Account opcionalprivacy:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

reason
string
requested_at
string (date-time)
keep_legal_hold
boolean

Ejemplo de solicitud

{
  "reason": "requested by the account",
  "requested_at": "2026-11-02T09:30:00+00:00",
  "keep_legal_hold": true
}

Ejemplo de respuesta · 202

{
  "id": "era_01JB6ZK8TQ0000000000000000",
  "object": "erasure_request",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "scope": "contact",
  "contact_id": "string",
  "status": "queued",
  "requested_via": "string",
  "receipt_sha256": "string",
  "items": [
    null
  ],
  "requested_at": "2026-11-02T09:30:00+00:00",
  "due_by": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00",
  "erasure_request_id": "era_01JB6ZK8TQ0000000000000000"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/accounts/{id}/erase

Request the cascade erasure of an account

privacy:write

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Cuerpo de la solicitud

reason
string
requested_at
string (date-time)
keep_legal_hold
boolean

Ejemplo de solicitud

{
  "reason": "requested by the account",
  "requested_at": "2026-11-02T09:30:00+00:00",
  "keep_legal_hold": true
}

Ejemplo de respuesta · 202

{
  "id": "era_01JB6ZK8TQ0000000000000000",
  "object": "erasure_request",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "scope": "contact",
  "contact_id": "string",
  "status": "queued",
  "requested_via": "string",
  "receipt_sha256": "string",
  "items": [
    null
  ],
  "requested_at": "2026-11-02T09:30:00+00:00",
  "due_by": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00",
  "erasure_request_id": "era_01JB6ZK8TQ0000000000000000"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/erasure_requests/{id}

Retrieve an erasure request and its receipt

Tact-Account opcionalprivacy:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "era_01JB6ZK8TQ0000000000000000",
  "object": "erasure_request",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "scope": "contact",
  "contact_id": "string",
  "status": "queued",
  "requested_via": "string",
  "receipt_sha256": "string",
  "items": [
    null
  ],
  "requested_at": "2026-11-02T09:30:00+00:00",
  "due_by": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Threads8 rutas

GET/v1/threads

List threads

Tact-Account obligatoriothreads:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string
mode
query · "assistant" | "representative"
contact_id
query · string
expand[]
query · "contact" | "agent"

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "thr_01JB6ZK8TQ0000000000000000",
      "object": "thread",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "contact_id": "con_01JB6ZK8TQ0000000000000000",
      "mode": "assistant",
      "status": "open",
      "channels": [
        "whatsapp"
      ],
      "window_open_until": "2026-11-02T09:30:00+00:00",
      "disclosed_at": "2026-11-02T09:30:00+00:00",
      "last_inbound_at": "2026-11-02T09:30:00+00:00",
      "last_outbound_at": "2026-11-02T09:30:00+00:00",
      "last_message_at": "2026-11-02T09:30:00+00:00",
      "open_goals": [
        {
          "id": "gol_01JB6ZK8TQ0000000000000000",
          "kind": "string",
          "status": "string"
        }
      ],
      "contact": {},
      "agent": {},
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/threads/{id}

Retrieve a thread

Tact-Account opcionalthreads:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
expand[]
query · "contact" | "agent"

Ejemplo de respuesta · 200

{
  "id": "thr_01JB6ZK8TQ0000000000000000",
  "object": "thread",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "mode": "assistant",
  "status": "open",
  "channels": [
    "whatsapp"
  ],
  "window_open_until": "2026-11-02T09:30:00+00:00",
  "disclosed_at": "2026-11-02T09:30:00+00:00",
  "last_inbound_at": "2026-11-02T09:30:00+00:00",
  "last_outbound_at": "2026-11-02T09:30:00+00:00",
  "last_message_at": "2026-11-02T09:30:00+00:00",
  "open_goals": [
    {
      "id": "gol_01JB6ZK8TQ0000000000000000",
      "kind": "string",
      "status": "string"
    }
  ],
  "contact": {},
  "agent": {},
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/threads/{id}/handoff

Hand the thread to the team

Tact-Account opcionalthreads:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

reason
string
note
string
notify_contact
boolean

Ejemplo de solicitud

{
  "reason": "requested by the account",
  "note": "string",
  "notify_contact": true
}

Ejemplo de respuesta · 200

{
  "id": "thr_01JB6ZK8TQ0000000000000000",
  "object": "thread",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "mode": "assistant",
  "status": "open",
  "channels": [
    "whatsapp"
  ],
  "window_open_until": "2026-11-02T09:30:00+00:00",
  "disclosed_at": "2026-11-02T09:30:00+00:00",
  "last_inbound_at": "2026-11-02T09:30:00+00:00",
  "last_outbound_at": "2026-11-02T09:30:00+00:00",
  "last_message_at": "2026-11-02T09:30:00+00:00",
  "open_goals": [
    {
      "id": "gol_01JB6ZK8TQ0000000000000000",
      "kind": "string",
      "status": "string"
    }
  ],
  "contact": {},
  "agent": {},
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/threads/{id}/release

Give the thread back to the agent

Tact-Account opcionalthreads:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "thr_01JB6ZK8TQ0000000000000000",
  "object": "thread",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "mode": "assistant",
  "status": "open",
  "channels": [
    "whatsapp"
  ],
  "window_open_until": "2026-11-02T09:30:00+00:00",
  "disclosed_at": "2026-11-02T09:30:00+00:00",
  "last_inbound_at": "2026-11-02T09:30:00+00:00",
  "last_outbound_at": "2026-11-02T09:30:00+00:00",
  "last_message_at": "2026-11-02T09:30:00+00:00",
  "open_goals": [
    {
      "id": "gol_01JB6ZK8TQ0000000000000000",
      "kind": "string",
      "status": "string"
    }
  ],
  "contact": {},
  "agent": {},
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/threads/import

Import message history (legacy_import)

Tact-Account obligatoriothreads:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

contact_id
string
contact_external_ref
string
from
string
Channel address when the contact is new
channelobligatorio
"whatsapp" | "sms" | "email" | "voice" | "telegram" | "in_app" | "imessage"
origin
"legacy_import"
messagesobligatorio
object[]

Ejemplo de solicitud

{
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "contact_external_ref": "string",
  "from": "string",
  "channel": "whatsapp",
  "origin": "legacy_import",
  "messages": [
    {
      "direction": "in",
      "author": "string",
      "text": "Can I move Thursday to Friday?",
      "sent_at": "2026-11-02T09:30:00+00:00",
      "provider_message_id": "string",
      "generated_by_ai": true
    }
  ]
}

Ejemplo de respuesta · 201

{
  "object": "thread_import",
  "origin": "string",
  "thread_id": "thr_01JB6ZK8TQ0000000000000000",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "imported": 1,
  "skipped": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/threads/{id}/messages

List messages, newest first

Tact-Account opcionalthreads:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "msg_01JB6ZK8TQ0000000000000000",
      "object": "message",
      "thread_id": "thr_01JB6ZK8TQ0000000000000000",
      "direction": "in",
      "author": "string",
      "channel": "whatsapp",
      "kind": "string",
      "text": "Can I move Thursday to Friday?",
      "provider_message_id": "string",
      "proactive": true,
      "generated_by_ai": true,
      "delivery_status": "string",
      "run_id": "string",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/threads/{id}/messages

Send a human message from the team through the thread

The thread moves to handoff, so the agent stops answering until release.

Tact-Account opcionalthreads:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

author
"staff" | "principal"
textobligatorio
string
channel
"whatsapp" | "sms" | "email" | "voice" | "telegram" | "in_app" | "imessage"

Ejemplo de solicitud

{
  "author": "staff",
  "text": "Can I move Thursday to Friday?",
  "channel": "whatsapp"
}

Ejemplo de respuesta · 202

{
  "id": "msg_01JB6ZK8TQ0000000000000000",
  "object": "message",
  "thread_id": "thr_01JB6ZK8TQ0000000000000000",
  "direction": "in",
  "author": "string",
  "channel": "whatsapp",
  "kind": "string",
  "text": "Can I move Thursday to Friday?",
  "provider_message_id": "string",
  "proactive": true,
  "generated_by_ai": true,
  "delivery_status": "string",
  "run_id": "string",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/inbound

Deliver a message from the tenant's own channel; shadow mode drafts without sending

Tact-Account obligatoriothreads:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

idobligatorio
string
Tenant message id, used for deduplication
channel
"whatsapp" | "sms" | "email" | "voice" | "telegram" | "in_app" | "imessage"
contact_id
string
contact_external_ref
string
from
string
textobligatorio
string
sent_at
string (date-time)
shadow
boolean
Draft without sending (shadow mode)

Ejemplo de solicitud

{
  "id": "msg_9001",
  "channel": "whatsapp",
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "contact_external_ref": "string",
  "from": "string",
  "text": "Can I move Thursday to Friday?",
  "sent_at": "2026-11-02T09:30:00+00:00",
  "shadow": false
}

Ejemplo de respuesta · 202

{
  "object": "inbound",
  "inbound_event_id": 1,
  "contact_id": "con_01JB6ZK8TQ0000000000000000",
  "deduplicated": true,
  "shadow": false
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Goals5 rutas

GET/v1/goals

List goals

Tact-Account obligatoriogoals:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "gol_01JB6ZK8TQ0000000000000000",
      "object": "goal",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "title": "string",
      "kind": "string",
      "params": {},
      "status": "active",
      "created_by": "string",
      "deadline": "2026-11-02T09:30:00+00:00",
      "thread_id": "string",
      "root_task_id": "tsk_01JB6ZK8TQ0000000000000000",
      "created_at": "2026-11-02T09:30:00+00:00",
      "completed_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/goals

Create a durable goal

Tact-Account obligatoriogoals:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

agent_id
string
kindobligatorio
string
title
string
params
object
deadline
string (date-time)
created_by
"principal" | "tenant_api"
requested_by_principal_id
string
thread_id
string

Ejemplo de solicitud

{
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "kind": "string",
  "title": "string",
  "params": {},
  "deadline": "2026-11-02T09:30:00+00:00",
  "created_by": "principal",
  "requested_by_principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "thread_id": "thr_01JB6ZK8TQ0000000000000000"
}

Ejemplo de respuesta · 201

{
  "id": "gol_01JB6ZK8TQ0000000000000000",
  "object": "goal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "title": "string",
  "kind": "string",
  "params": {},
  "status": "active",
  "created_by": "string",
  "deadline": "2026-11-02T09:30:00+00:00",
  "thread_id": "string",
  "root_task_id": "tsk_01JB6ZK8TQ0000000000000000",
  "created_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/goals/{id}

Retrieve a goal

Tact-Account opcionalgoals:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "gol_01JB6ZK8TQ0000000000000000",
  "object": "goal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "title": "string",
  "kind": "string",
  "params": {},
  "status": "active",
  "created_by": "string",
  "deadline": "2026-11-02T09:30:00+00:00",
  "thread_id": "string",
  "root_task_id": "tsk_01JB6ZK8TQ0000000000000000",
  "created_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/goals/{id}/cancel

Cancel a goal and its open tasks

Tact-Account opcionalgoals:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "gol_01JB6ZK8TQ0000000000000000",
  "object": "goal",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "title": "string",
  "kind": "string",
  "params": {},
  "status": "active",
  "created_by": "string",
  "deadline": "2026-11-02T09:30:00+00:00",
  "thread_id": "string",
  "root_task_id": "tsk_01JB6ZK8TQ0000000000000000",
  "created_at": "2026-11-02T09:30:00+00:00",
  "completed_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/goals/{id}/tasks

List the tasks of a goal

Tact-Account opcionalgoals:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "tsk_01JB6ZK8TQ0000000000000000",
      "object": "task",
      "goal_id": "string",
      "thread_id": "string",
      "kind": "string",
      "state": "open",
      "wake_at": "2026-11-02T09:30:00+00:00",
      "deadline_at": "2026-11-02T09:30:00+00:00",
      "attempts": 1,
      "created_at": "2026-11-02T09:30:00+00:00",
      "updated_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Memory4 rutas

GET/v1/memories

List memories

Tact-Account obligatoriomemory:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
kind
query · string
subject_type
query · "contact" | "principal" | "account" | "agent"
subject_id
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "mem_01JB6ZK8TQ0000000000000000",
      "object": "memory",
      "subject": {
        "type": "contact",
        "id": "msg_9001"
      },
      "kind": "string",
      "content": "string",
      "origin": "string",
      "trust": "low",
      "confidence": 1.5,
      "sensitivity": "string",
      "valid_from": "2026-11-02T09:30:00+00:00",
      "valid_until": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "result": "string"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/memories

Write a memory with its origin

Tact-Account obligatoriomemory:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

subjectobligatorio
object
kindobligatorio
"preference" | "fact" | "commitment" | "instruction" | "knowledge"
contentobligatorio
string
origin
"contact" | "principal" | "staff" | "tenant"
What a contact says never becomes an instruction
confidence
number
sensitivity
"none" | "personal" | "health"
source_ref
string
valid_until
string (date-time)

Ejemplo de solicitud

{
  "subject": {
    "type": "contact",
    "id": "msg_9001"
  },
  "kind": "preference",
  "content": "string",
  "origin": "contact",
  "confidence": 1.5,
  "sensitivity": "none",
  "source_ref": "msg_01JB6ZK8TQ0000000000000000",
  "valid_until": "2026-11-02T09:30:00+00:00"
}

Ejemplo de respuesta · 201

{
  "id": "mem_01JB6ZK8TQ0000000000000000",
  "object": "memory",
  "subject": {
    "type": "contact",
    "id": "msg_9001"
  },
  "kind": "string",
  "content": "string",
  "origin": "string",
  "trust": "low",
  "confidence": 1.5,
  "sensitivity": "string",
  "valid_from": "2026-11-02T09:30:00+00:00",
  "valid_until": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "result": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

DELETE/v1/memories/{id}

Forget one memory

Tact-Account opcionalmemory:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "msg_9001",
  "object": "string",
  "deleted": true
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/memories/forget

Forget what matches a query about a subject

Tact-Account obligatoriomemory:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

subjectobligatorio
object
query
string
requested_by
"contact" | "principal" | "staff" | "tenant"

Ejemplo de solicitud

{
  "subject": {
    "type": "contact",
    "id": "msg_9001"
  },
  "query": "string",
  "requested_by": "contact"
}

Ejemplo de respuesta · 200

{
  "object": "forget_result",
  "requested_by": "string",
  "forgotten": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Policy6 rutas

GET/v1/policy_rules

List policy rules (tenant level, plus account and agent with Tact-Account)

Tact-Account opcionalpolicies:read

Parámetros

Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string
level
query · "pack" | "tenant" | "account" | "agent" | "grant"
action_type
query · string
include_expired
query · boolean

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "pol_01JB6ZK8TQ0000000000000000",
      "object": "policy_rule",
      "level": "pack",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "action_type": "string",
      "decision": "allow",
      "otherwise": "ask",
      "min_effect": "string",
      "max_effect": "string",
      "locked": true,
      "conditions": [
        {
          "fact": "appointment.hours_until_start",
          "op": "eq",
          "value": null
        }
      ],
      "approver_role": "string",
      "source": "string",
      "explanation": null,
      "nl_text": "string",
      "priority": 1,
      "valid_from": "2026-11-02T09:30:00+00:00",
      "valid_until": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/policy_rules

Create a policy rule within the engine floor

Tact-Account opcionalpolicies:write

Parámetros

Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

levelobligatorio
"tenant" | "account" | "agent"
agent_id
string
action_typeobligatorio
string
Action type of the engine taxonomy (data.read, message.reply, schedule.cancel ...) or a pack tool name
decisionobligatorio
"allow" | "ask" | "block"
conditions
object[]
Only for allow; when a condition fails the decision is ask
otherwise
"ask"
locked
boolean
Lower levels cannot be more permissive
priority
integer
valid_until
string (date-time)
explanation
object
Text per locale shown to the principal
approver_role
string

Ejemplo de solicitud

{
  "level": "tenant",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "action_type": "string",
  "decision": "allow",
  "conditions": [
    {
      "fact": "appointment.hours_until_start",
      "op": "eq",
      "value": null
    }
  ],
  "otherwise": "ask",
  "locked": true,
  "priority": 1,
  "valid_until": "2026-11-02T09:30:00+00:00",
  "explanation": {},
  "approver_role": "string"
}

Ejemplo de respuesta · 201

{
  "id": "pol_01JB6ZK8TQ0000000000000000",
  "object": "policy_rule",
  "level": "pack",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "action_type": "string",
  "decision": "allow",
  "otherwise": "ask",
  "min_effect": "string",
  "max_effect": "string",
  "locked": true,
  "conditions": [
    {
      "fact": "appointment.hours_until_start",
      "op": "eq",
      "value": null
    }
  ],
  "approver_role": "string",
  "source": "string",
  "explanation": null,
  "nl_text": "string",
  "priority": 1,
  "valid_from": "2026-11-02T09:30:00+00:00",
  "valid_until": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/policy_rules/{id}

Update a policy rule

Tact-Account opcionalpolicies:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

decision
"allow" | "ask" | "block"
conditions
object[]
locked
boolean
priority
integer
valid_until
string (date-time)
explanation
object

Ejemplo de solicitud

{
  "decision": "allow",
  "conditions": [
    {
      "fact": "appointment.hours_until_start",
      "op": "eq",
      "value": null
    }
  ],
  "locked": true,
  "priority": 1,
  "valid_until": "2026-11-02T09:30:00+00:00",
  "explanation": {}
}

Ejemplo de respuesta · 200

{
  "id": "pol_01JB6ZK8TQ0000000000000000",
  "object": "policy_rule",
  "level": "pack",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "action_type": "string",
  "decision": "allow",
  "otherwise": "ask",
  "min_effect": "string",
  "max_effect": "string",
  "locked": true,
  "conditions": [
    {
      "fact": "appointment.hours_until_start",
      "op": "eq",
      "value": null
    }
  ],
  "approver_role": "string",
  "source": "string",
  "explanation": null,
  "nl_text": "string",
  "priority": 1,
  "valid_from": "2026-11-02T09:30:00+00:00",
  "valid_until": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

DELETE/v1/policy_rules/{id}

Expire a policy rule (history is kept)

Tact-Account opcionalpolicies:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "pol_01JB6ZK8TQ0000000000000000",
  "object": "policy_rule",
  "level": "pack",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "action_type": "string",
  "decision": "allow",
  "otherwise": "ask",
  "min_effect": "string",
  "max_effect": "string",
  "locked": true,
  "conditions": [
    {
      "fact": "appointment.hours_until_start",
      "op": "eq",
      "value": null
    }
  ],
  "approver_role": "string",
  "source": "string",
  "explanation": null,
  "nl_text": "string",
  "priority": 1,
  "valid_from": "2026-11-02T09:30:00+00:00",
  "valid_until": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/policies/effective

Effective decision per action type

Tact-Account obligatoriopolicies:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
face
query · "assistant" | "representative"

Ejemplo de respuesta · 200

{
  "object": "effective_policy",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "face": "string",
  "data": [
    {
      "action_type": "string",
      "action_class": "string",
      "decision": "allow",
      "otherwise": "allow",
      "binding": "string",
      "conditions": [
        {
          "fact": "appointment.hours_until_start",
          "op": "eq",
          "value": null
        }
      ],
      "rule_ids": [
        "string"
      ],
      "source": "floor"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/policies/simulate

Simulate a decision with given facts

Tact-Account obligatoriopolicies:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

agent_id
string
action_typeobligatorio
string
Action type of the engine taxonomy (data.read, message.reply, schedule.cancel ...) or a pack tool name
facts
object
Fact name to value
face
"assistant" | "representative"

Ejemplo de solicitud

{
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "action_type": "string",
  "facts": {},
  "face": "assistant"
}

Ejemplo de respuesta · 200

{
  "object": "policy_simulation",
  "action_type": "string",
  "face": "string",
  "decision": "allow",
  "binding": "string",
  "reason": "requested by the account",
  "matched_rules": [
    {
      "id": "pol_01JB6ZK8TQ0000000000000000",
      "level": "string",
      "decision": "allow"
    }
  ],
  "conditions_failed": [
    "string"
  ],
  "trace": [
    {}
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Approvals3 rutas

GET/v1/approvals

List approvals

Tact-Account obligatorioapprovals:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "apr_01JB6ZK8TQ0000000000000000",
      "object": "approval",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "status": "pending",
      "action": {
        "id": "act_01JB6ZK8TQ0000000000000000",
        "action_type": "string",
        "tool": "string"
      },
      "action_class": "string",
      "risk": "low",
      "binding": "loose_tap",
      "summary": {},
      "summary_hash": "string",
      "args": {},
      "requested_from": [
        "prn_01JB6ZK8TQ0000000000000000"
      ],
      "approver_role": "string",
      "channel": "string",
      "requested_at": "2026-11-02T09:30:00+00:00",
      "expires_at": "2026-11-02T09:30:00+00:00",
      "reminders_sent": 1,
      "decided_at": "2026-11-02T09:30:00+00:00",
      "decided_by": "string",
      "decided_via": "string",
      "rule_proposal": {}
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/approvals/{id}

Retrieve an approval

Tact-Account opcionalapprovals:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "apr_01JB6ZK8TQ0000000000000000",
  "object": "approval",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "status": "pending",
  "action": {
    "id": "act_01JB6ZK8TQ0000000000000000",
    "action_type": "string",
    "tool": "string"
  },
  "action_class": "string",
  "risk": "low",
  "binding": "loose_tap",
  "summary": {},
  "summary_hash": "string",
  "args": {},
  "requested_from": [
    "prn_01JB6ZK8TQ0000000000000000"
  ],
  "approver_role": "string",
  "channel": "string",
  "requested_at": "2026-11-02T09:30:00+00:00",
  "expires_at": "2026-11-02T09:30:00+00:00",
  "reminders_sent": 1,
  "decided_at": "2026-11-02T09:30:00+00:00",
  "decided_by": "string",
  "decided_via": "string",
  "rule_proposal": {}
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/approvals/{id}/decide

Approve or reject on behalf of a principal

Approving requires summary_hash from GET /v1/approvals/{id} (400 parameter_missing without it), so the principal approves exactly the summary that was shown. Critical approvals (security or destructive) are decided only in the console with step-up.

Tact-Account opcionalapprovals:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Cuerpo de la solicitud

decisionobligatorio
"approve" | "reject"
principal_idobligatorio
string
note
string
apply_as_rule
boolean
Proposes an account rule for the same case; the principal confirms it
summary_hash
string
summary_hash read from GET /v1/approvals/{id}. Required to approve: the decision binds to that exact summary and fails if it changed after the read. Optional to reject (without it the current summary applies)

Ejemplo de solicitud

{
  "decision": "approve",
  "principal_id": "prn_01JB6ZK8TQ0000000000000000",
  "note": "string",
  "apply_as_rule": true,
  "summary_hash": "string"
}

Ejemplo de respuesta · 200

{
  "id": "apr_01JB6ZK8TQ0000000000000000",
  "object": "approval",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "status": "pending",
  "action": {
    "id": "act_01JB6ZK8TQ0000000000000000",
    "action_type": "string",
    "tool": "string"
  },
  "action_class": "string",
  "risk": "low",
  "binding": "loose_tap",
  "summary": {},
  "summary_hash": "string",
  "args": {},
  "requested_from": [
    "prn_01JB6ZK8TQ0000000000000000"
  ],
  "approver_role": "string",
  "channel": "string",
  "requested_at": "2026-11-02T09:30:00+00:00",
  "expires_at": "2026-11-02T09:30:00+00:00",
  "reminders_sent": 1,
  "decided_at": "2026-11-02T09:30:00+00:00",
  "decided_by": "string",
  "decided_via": "string",
  "rule_proposal": {}
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Packs9 rutas

GET/v1/packs

List packs visible to the tenant

packs:read

Parámetros

limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "pck_01JB6ZK8TQ0000000000000000",
      "object": "pack",
      "key": "principal_verified",
      "name": "Harbour Physio",
      "owner": "amplitude",
      "versions": [
        {
          "id": "pkv_01JB6ZK8TQ0000000000000000",
          "object": "pack_version",
          "pack_id": "pck_01JB6ZK8TQ0000000000000000",
          "pack_key": "string",
          "version": "string",
          "status": "draft",
          "manifest_sha256": "string",
          "eval_run_id": "string",
          "activated_at": "2026-11-02T09:30:00+00:00",
          "created_at": "2026-11-02T09:30:00+00:00",
          "tools": [
            "string"
          ],
          "playbooks": [
            "string"
          ]
        }
      ],
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/packs

Create a tenant pack

packs:write

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

keyobligatorio
string
nameobligatorio
string

Ejemplo de solicitud

{
  "key": "principal_verified",
  "name": "Harbour Physio"
}

Ejemplo de respuesta · 201

{
  "id": "pck_01JB6ZK8TQ0000000000000000",
  "object": "pack",
  "key": "principal_verified",
  "name": "Harbour Physio",
  "owner": "amplitude",
  "versions": [
    {
      "id": "pkv_01JB6ZK8TQ0000000000000000",
      "object": "pack_version",
      "pack_id": "pck_01JB6ZK8TQ0000000000000000",
      "pack_key": "string",
      "version": "string",
      "status": "draft",
      "manifest_sha256": "string",
      "eval_run_id": "string",
      "activated_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00",
      "tools": [
        "string"
      ],
      "playbooks": [
        "string"
      ]
    }
  ],
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/packs/{id}/versions

Create or replace a draft version with its manifest

packs:write

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Cuerpo de la solicitud

versionobligatorio
string
SemVer
manifestobligatorio
object
Pack manifest: tools (JSON Schema 2020-12, strict), playbooks, prerequisites, knowledge_schemas, locales

Ejemplo de solicitud

{
  "version": "string",
  "manifest": {}
}

Ejemplo de respuesta · 201

{
  "id": "pkv_01JB6ZK8TQ0000000000000000",
  "object": "pack_version",
  "pack_id": "pck_01JB6ZK8TQ0000000000000000",
  "pack_key": "string",
  "version": "string",
  "status": "draft",
  "manifest_sha256": "string",
  "eval_run_id": "string",
  "activated_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "tools": [
    "string"
  ],
  "playbooks": [
    "string"
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/packs/{id}/versions/{v}/evaluate

Run the eval suites of a draft version

packs:write

Parámetros

idobligatorio
path · string
vobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 202

{
  "object": "eval_run",
  "id": "evr_01JB6ZK8TQ0000000000000000",
  "pack_version_id": "pkv_01JB6ZK8TQ0000000000000000",
  "status": "queued",
  "passed": true
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/packs/{id}/versions/{v}/activate

Activate a version whose evals passed

packs:write

Parámetros

idobligatorio
path · string
vobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "pkv_01JB6ZK8TQ0000000000000000",
  "object": "pack_version",
  "pack_id": "pck_01JB6ZK8TQ0000000000000000",
  "pack_key": "string",
  "version": "string",
  "status": "draft",
  "manifest_sha256": "string",
  "eval_run_id": "string",
  "activated_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "tools": [
    "string"
  ],
  "playbooks": [
    "string"
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/pack_installs

Install an active pack version on the account

Tact-Account obligatoriopacks:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

packobligatorio
object
playbooks
object

Ejemplo de solicitud

{
  "pack": {
    "id": "msg_9001",
    "key": "principal_verified",
    "version": "string"
  },
  "playbooks": {}
}

Ejemplo de respuesta · 200

{
  "id": "pin_01JB6ZK8TQ0000000000000000",
  "object": "pack_install",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string",
    "version_id": "pkv_01JB6ZK8TQ0000000000000000"
  },
  "playbooks": {}
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/pack_installs/{id}

Turn playbooks on or off

Tact-Account opcionalpacks:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Cuerpo de la solicitud

playbooks
object

Ejemplo de solicitud

{
  "playbooks": {
    "key": "on"
  }
}

Ejemplo de respuesta · 200

{
  "id": "pin_01JB6ZK8TQ0000000000000000",
  "object": "pack_install",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "pack": {
    "id": "pck_01JB6ZK8TQ0000000000000000",
    "key": "principal_verified",
    "version": "string",
    "version_id": "pkv_01JB6ZK8TQ0000000000000000"
  },
  "playbooks": {}
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/tools

Effective tool catalog of the account

Tact-Account obligatoriopacks:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "tool",
      "name": "Harbour Physio",
      "description": "string",
      "action_type": "string",
      "action_class": "string",
      "risk": "string",
      "modes": [
        "string"
      ],
      "input_schema": {},
      "output_schema": {},
      "facts": [
        "string"
      ],
      "timeout_ms": 1,
      "idempotent": true
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/tools/{name}/dry_run

Validate arguments against a tool schema without calling the tenant

Tact-Account obligatoriopacks:read

Parámetros

nameobligatorio
path · string
Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

args
object
mode
"assistant" | "representative"

Ejemplo de solicitud

{
  "args": {},
  "mode": "assistant"
}

Ejemplo de respuesta · 200

{
  "object": "tool_dry_run",
  "tool": "string",
  "action_type": "string",
  "mode": "string",
  "available_in_mode": true,
  "valid": true,
  "issues": [
    {
      "path": "string",
      "keyword": "string",
      "message": "Contact has no active consent for purpose 'recall' on channel 'whatsapp'."
    }
  ],
  "args_sha256": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Triggers5 rutas

POST/v1/events

Send a business event (deduplicated by event id for 7 days)

knowledge.upsert and knowledge.delete events update the account knowledge right away.

Tact-Account obligatorioevents:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

idobligatorio
string
Tenant event id; deduplicated for 7 days
typeobligatorio
string
occurred_atobligatorio
string (date-time)
data
object
knowledge.upsert: {kind, external_ref, source_updated_at, data}; knowledge.delete: {kind, external_ref}

Ejemplo de solicitud

{
  "id": "msg_9001",
  "type": "appointment.cancelled",
  "occurred_at": "2026-11-02T09:30:00+00:00",
  "data": {}
}

Ejemplo de respuesta · 202

{
  "object": "event_receipt",
  "trigger_id": "trg_01JB6ZK8TQ0000000000000000",
  "deduplicated": true,
  "applied": {}
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/schedules

List schedules

Tact-Account obligatorioevents:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "trg_01JB6ZK8TQ0000000000000000",
      "object": "schedule",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "kind": "string",
      "playbook_key": "string",
      "spec": {},
      "next_fire_at": "2026-11-02T09:30:00+00:00",
      "enabled": true,
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/schedules

Schedule a playbook (RRULE in the account time zone, or a single instant)

Tact-Account obligatorioevents:write

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
Idempotency-Key
header · string

Cuerpo de la solicitud

playbook_keyobligatorio
string
rrule
string
RRULE:... in the time zone
at
string (date-time)
timezone
string
Defaults to the account time zone
payload
object

Ejemplo de solicitud

{
  "playbook_key": "string",
  "rrule": "string",
  "at": "2026-11-02T09:30:00+00:00",
  "timezone": "Europe/Dublin",
  "payload": {}
}

Ejemplo de respuesta · 201

{
  "id": "trg_01JB6ZK8TQ0000000000000000",
  "object": "schedule",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "kind": "string",
  "playbook_key": "string",
  "spec": {},
  "next_fire_at": "2026-11-02T09:30:00+00:00",
  "enabled": true,
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

DELETE/v1/schedules/{id}

Disable a schedule

Tact-Account opcionalevents:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "trg_01JB6ZK8TQ0000000000000000",
  "object": "schedule",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "kind": "string",
  "playbook_key": "string",
  "spec": {},
  "next_fire_at": "2026-11-02T09:30:00+00:00",
  "enabled": true,
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/functions/v1/ingress-tenant/{tenant}

Push business events from the tenant outbox (signed)

Sign the raw body with the secret from POST /v1/tenant/outbox_secret: Tact-Signature: t=<unix>,v1=hex(hmac_sha256(secret, t + "." + body)). Tolerance 5 minutes. Body: {account, events: [...]} with up to 100 events; each event may carry its own account (acc_... or ext:<external_ref>).

Sin autenticación

Parámetros

tenantobligatorio
path · string
ten_ id or tenant slug
Tact-Signatureobligatorio
header · string

Cuerpo de la solicitud

account
string
events
object[]

Ejemplo de solicitud

{
  "account": "string",
  "events": [
    {
      "id": "msg_9001",
      "type": "appointment.cancelled",
      "occurred_at": "2026-11-02T09:30:00+00:00",
      "data": {},
      "account": "string"
    }
  ]
}

Ejemplo de respuesta · 202

{
  "object": "outbox_receipt",
  "received": 1,
  "deduplicated": 1,
  "rejected": [
    {}
  ]
}

Errores · 401

401Authentication failed (key_invalid, key_revoked, key_expired)

Runs5 rutas

GET/v1/runs

List runs

Tact-Account obligatoriothreads:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string
thread_id
query · string
created_after
query · string (date-time)

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "run_01JB6ZK8TQ0000000000000000",
      "object": "run",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "thread_id": "string",
      "task_id": "string",
      "status": "queued",
      "outcome": "string",
      "trigger": {
        "kind": "string",
        "ref": "string"
      },
      "foreground": true,
      "step_count": 1,
      "models_used": [
        "string"
      ],
      "cost": {
        "model_usd_micros": 1,
        "channel_micros": 1,
        "voice_micros": 1,
        "tools_micros": 1,
        "channel": [
          {
            "currency": "EUR",
            "amount_micros": 1,
            "items": 1,
            "category": "string"
          }
        ]
      },
      "error_code": "string",
      "latency_ms": 1,
      "queued_at": "2026-11-02T09:30:00+00:00",
      "started_at": "2026-11-02T09:30:00+00:00",
      "finished_at": "2026-11-02T09:30:00+00:00",
      "steps": [
        {
          "n": 1,
          "kind": "string",
          "model": "string",
          "verdict": "string",
          "latency_ms": 1,
          "created_at": "2026-11-02T09:30:00+00:00"
        }
      ],
      "actions": [
        {
          "id": "act_01JB6ZK8TQ0000000000000000",
          "action_type": "string",
          "verdict": "string",
          "status": "string"
        }
      ]
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/runs/{id}

Retrieve a run with steps, actions and cost

Tact-Account opcionalthreads:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "run_01JB6ZK8TQ0000000000000000",
  "object": "run",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "thread_id": "string",
  "task_id": "string",
  "status": "queued",
  "outcome": "string",
  "trigger": {
    "kind": "string",
    "ref": "string"
  },
  "foreground": true,
  "step_count": 1,
  "models_used": [
    "string"
  ],
  "cost": {
    "model_usd_micros": 1,
    "channel_micros": 1,
    "voice_micros": 1,
    "tools_micros": 1,
    "channel": [
      {
        "currency": "EUR",
        "amount_micros": 1,
        "items": 1,
        "category": "string"
      }
    ]
  },
  "error_code": "string",
  "latency_ms": 1,
  "queued_at": "2026-11-02T09:30:00+00:00",
  "started_at": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00",
  "steps": [
    {
      "n": 1,
      "kind": "string",
      "model": "string",
      "verdict": "string",
      "latency_ms": 1,
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "actions": [
    {
      "id": "act_01JB6ZK8TQ0000000000000000",
      "action_type": "string",
      "verdict": "string",
      "status": "string"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/runs/{id}/cancel

Cancel a queued or running run

Tact-Account opcionalthreads:write

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "run_01JB6ZK8TQ0000000000000000",
  "object": "run",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "thread_id": "string",
  "task_id": "string",
  "status": "queued",
  "outcome": "string",
  "trigger": {
    "kind": "string",
    "ref": "string"
  },
  "foreground": true,
  "step_count": 1,
  "models_used": [
    "string"
  ],
  "cost": {
    "model_usd_micros": 1,
    "channel_micros": 1,
    "voice_micros": 1,
    "tools_micros": 1,
    "channel": [
      {
        "currency": "EUR",
        "amount_micros": 1,
        "items": 1,
        "category": "string"
      }
    ]
  },
  "error_code": "string",
  "latency_ms": 1,
  "queued_at": "2026-11-02T09:30:00+00:00",
  "started_at": "2026-11-02T09:30:00+00:00",
  "finished_at": "2026-11-02T09:30:00+00:00",
  "steps": [
    {
      "n": 1,
      "kind": "string",
      "model": "string",
      "verdict": "string",
      "latency_ms": 1,
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ],
  "actions": [
    {
      "id": "act_01JB6ZK8TQ0000000000000000",
      "action_type": "string",
      "verdict": "string",
      "status": "string"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/actions

Audit trail of actions

Tact-Account obligatoriothreads:read

Parámetros

Tact-Accountobligatorio
header · string
acc_... or ext:<external_ref>
limit
query · integer
cursor
query · string
status
query · string
action_type
query · string
run_id
query · string
thread_id
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "act_01JB6ZK8TQ0000000000000000",
      "object": "action",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "run_id": "string",
      "thread_id": "string",
      "action_type": "string",
      "tool": "string",
      "action_class": "string",
      "risk": "string",
      "status": "string",
      "policy_decision": "allow",
      "guardian_verdict": "string",
      "approval_id": "string",
      "target_contact_id": "string",
      "args_sha256": "string",
      "generated_by_ai": true,
      "result_summary": {},
      "cost_micros": 1,
      "seq": 1,
      "row_hash": "string",
      "created_at": "2026-11-02T09:30:00+00:00",
      "executed_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/actions/{id}

Retrieve an action

Tact-Account opcionalthreads:read

Parámetros

idobligatorio
path · string
Tact-Account
header · string
When sent, the object must belong to this account

Ejemplo de respuesta · 200

{
  "id": "act_01JB6ZK8TQ0000000000000000",
  "object": "action",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "agent_id": "agt_01JB6ZK8TQ0000000000000000",
  "run_id": "string",
  "thread_id": "string",
  "action_type": "string",
  "tool": "string",
  "action_class": "string",
  "risk": "string",
  "status": "string",
  "policy_decision": "allow",
  "guardian_verdict": "string",
  "approval_id": "string",
  "target_contact_id": "string",
  "args_sha256": "string",
  "generated_by_ai": true,
  "result_summary": {},
  "cost_micros": 1,
  "seq": 1,
  "row_hash": "string",
  "created_at": "2026-11-02T09:30:00+00:00",
  "executed_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Usage3 rutas

GET/v1/usage

Usage events

Tact-Account opcionalusage:read

Parámetros

Tact-Account
header · string
When sent, the object must belong to this account
limit
query · integer
cursor
query · string
account_id
query · string
kind
query · string
from
query · string (date-time)
to
query · string (date-time)

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "msg_9001",
      "object": "usage_event",
      "account_id": "acc_01JB6ZK8TQ0000000000000000",
      "agent_id": "agt_01JB6ZK8TQ0000000000000000",
      "thread_id": "string",
      "run_id": "string",
      "kind": "string",
      "purpose": "string",
      "quantity": 1.5,
      "cost_usd_micros": 1,
      "cost_source": {
        "amount": 1.5,
        "currency": "EUR"
      },
      "payer": "string",
      "within_free_quota": true,
      "occurred_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/usage/summary

Monthly summary per account (UTC month)

Tact-Account opcionalusage:read

Parámetros

Tact-Account
header · string
When sent, the object must belong to this account
period
query · string
group_by
query · "account" | "tenant"

Ejemplo de respuesta · 200

{
  "object": "usage_summary",
  "period": "string",
  "timezone": "UTC",
  "group_by": "account",
  "data": [
    {}
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PUT/v1/budgets/{account_id}

Set the monthly budget of an account

accounts:write

Parámetros

account_idobligatorio
path · string

Cuerpo de la solicitud

monthly_usd_microsobligatorio
integer
on_exceed
"alert" | "degrade" | "block"
category
"model" | "channel" | "voice" | "browser" | "all"

Ejemplo de solicitud

{
  "monthly_usd_micros": 1,
  "on_exceed": "alert",
  "category": "model"
}

Ejemplo de respuesta · 200

{
  "id": "bud_01JB6ZK8TQ0000000000000000",
  "object": "budget",
  "account_id": "acc_01JB6ZK8TQ0000000000000000",
  "period": "string",
  "category": "string",
  "currency": "EUR",
  "limit_usd_micros": 1,
  "spent_usd_micros": 1,
  "period_start": "string",
  "on_exceed": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

Webhooks7 rutas

GET/v1/webhook_endpoints

List webhook endpoints

admin

Parámetros

limit
query · integer
cursor
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "whe_01JB6ZK8TQ0000000000000000",
      "object": "webhook_endpoint",
      "url": "https://example.com/tact/webhooks",
      "events": [
        "string"
      ],
      "include_text": true,
      "api_version": "string",
      "description": "string",
      "status": "enabled",
      "failures": 1,
      "disabled_at": "2026-11-02T09:30:00+00:00",
      "previous_secret_expires_at": "2026-11-02T09:30:00+00:00",
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/webhook_endpoints

Create a webhook endpoint (secret shown once)

admin

Parámetros

Idempotency-Key
header · string

Cuerpo de la solicitud

urlobligatorio
string
Public https URL
eventsobligatorio
string[]
include_text
boolean
Include message text and approval summaries
api_version
string
description
string

Ejemplo de solicitud

{
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "api_version": "string",
  "description": "string"
}

Ejemplo de respuesta · 201

{
  "id": "whe_01JB6ZK8TQ0000000000000000",
  "object": "webhook_endpoint",
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "api_version": "string",
  "description": "string",
  "status": "enabled",
  "failures": 1,
  "disabled_at": "2026-11-02T09:30:00+00:00",
  "previous_secret_expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "secret": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

admin

Parámetros

idobligatorio
path · string

Ejemplo de respuesta · 200

{
  "id": "whe_01JB6ZK8TQ0000000000000000",
  "object": "webhook_endpoint",
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "api_version": "string",
  "description": "string",
  "status": "enabled",
  "failures": 1,
  "disabled_at": "2026-11-02T09:30:00+00:00",
  "previous_secret_expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

PATCH/v1/webhook_endpoints/{id}

Update or re-enable a webhook endpoint

admin

Parámetros

idobligatorio
path · string

Cuerpo de la solicitud

url
string
events
string[]
include_text
boolean
description
string
enabled
boolean
true re-enables and resets the failure count

Ejemplo de solicitud

{
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "description": "string",
  "enabled": true
}

Ejemplo de respuesta · 200

{
  "id": "whe_01JB6ZK8TQ0000000000000000",
  "object": "webhook_endpoint",
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "api_version": "string",
  "description": "string",
  "status": "enabled",
  "failures": 1,
  "disabled_at": "2026-11-02T09:30:00+00:00",
  "previous_secret_expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/webhook_endpoints/{id}/rotate_secret

Rotate the secret; the previous one stays valid for 24 h

admin

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Ejemplo de respuesta · 200

{
  "id": "whe_01JB6ZK8TQ0000000000000000",
  "object": "webhook_endpoint",
  "url": "https://example.com/tact/webhooks",
  "events": [
    "string"
  ],
  "include_text": true,
  "api_version": "string",
  "description": "string",
  "status": "enabled",
  "failures": 1,
  "disabled_at": "2026-11-02T09:30:00+00:00",
  "previous_secret_expires_at": "2026-11-02T09:30:00+00:00",
  "created_at": "2026-11-02T09:30:00+00:00",
  "secret": "string"
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

POST/v1/webhook_endpoints/{id}/replay

Redeliver the events of a time range

admin

Parámetros

idobligatorio
path · string
Idempotency-Key
header · string

Cuerpo de la solicitud

fromobligatorio
string (date-time)
to
string (date-time)
event_types
string[]

Ejemplo de solicitud

{
  "from": "2026-11-02T09:30:00+00:00",
  "to": "2026-11-02T09:30:00+00:00",
  "event_types": [
    "string"
  ]
}

Ejemplo de respuesta · 200

{
  "object": "webhook_replay",
  "endpoint_id": "whe_01JB6ZK8TQ0000000000000000",
  "deliveries": 1
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

GET/v1/webhook_deliveries

List deliveries

admin

Parámetros

limit
query · integer
cursor
query · string
endpoint_id
query · string
status
query · string
event_type
query · string

Ejemplo de respuesta · 200

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "msg_9001",
      "object": "webhook_delivery",
      "endpoint_id": "whe_01JB6ZK8TQ0000000000000000",
      "event_id": "evt_01JB6ZK8TQ0000000000000000",
      "event_type": "string",
      "status": "pending",
      "attempt": 1,
      "next_attempt_at": "2026-11-02T09:30:00+00:00",
      "last_status_code": 1,
      "created_at": "2026-11-02T09:30:00+00:00"
    }
  ]
}

Errores · 400 401 403 404 409 422 429

400Invalid request (parameter_missing, parameter_invalid, scope_in_body, unsupported_locale, phone_not_e164)
401Authentication failed (key_invalid, key_revoked, key_expired)
403Permission denied (scope_missing, account_not_in_tenant, dpa_not_signed, principal_not_allowed_to_approve)
404Not found (resource_missing)
409Conflict (idempotency_key_reused, approval_already_decided, pack_version_immutable)
422Policy or pack error (blocked_by_floor, content_policy_violation, missing_prerequisite, evals_not_passed, tool_schema_invalid)
429Rate limited (rate_limited, budget_exhausted); see Retry-After

URL base

Autenticación

Alcance de Account

Idempotencia

Models2 rutas

List the Tact models (OpenAI compatible)

Chat completion (OpenAI compatible; stream with stream: true)

Parámetros

Cuerpo de la solicitud

Tenant8 rutas

Component status (no authentication)

Public keys of the Tact-Envelope sent on tool calls and outbox pulls (no authentication)

The authenticated tenant and key

Readiness checklist before going live

Create or rotate the secret that signs pushes to ingress-tenant

Parámetros

List API keys

Parámetros

Create an API key (secret shown once)

Parámetros

Cuerpo de la solicitud

Revoke an API key

Parámetros

Provisioning4 rutas

Read the provisioning template

Write the provisioning template every new account receives

Cuerpo de la solicitud

Roll the current template out to existing accounts (canary, then all after 48 h)

Parámetros

Cuerpo de la solicitud

Provision an account with its owner, agent, pack, policy, budget and onboarding (upsert by external_ref)

Parámetros

Cuerpo de la solicitud

Accounts7 rutas

List accounts

Parámetros

Retrieve an account

Parámetros

Update an account and mark onboarding steps done

Parámetros

Cuerpo de la solicitud

Pause an account

Parámetros

Resume a paused account

Parámetros

Close an account and schedule the cascade erasure

Parámetros

Cuerpo de la solicitud

Create a 15 minute session token for Tact Elements

Parámetros

Cuerpo de la solicitud

Principals6 rutas

List principals

Parámetros

Create or update a principal (upsert by external_ref)

Parámetros

Cuerpo de la solicitud

Retrieve a principal

Parámetros

Update a principal

Parámetros

Cuerpo de la solicitud

Add a channel to a principal and send a verification code

Parámetros

Cuerpo de la solicitud

Verify a principal channel with the 6 digit code (without code: resend it)

Parámetros

Cuerpo de la solicitud

Agent5 rutas

The agent of the account in Tact-Account

Parámetros

Retrieve an agent

Parámetros

Update persona, channels and overrides

Parámetros

Cuerpo de la solicitud

Pause the agent

Parámetros

Resume the agent

Parámetros