API REST

Qué conseguirá

Leerá y modificará su espacio de trabajo desde código y realizará una llamada saliente.

URL base y autenticación

URL base: https://phynxa.com/api. Todos los cuerpos son JSON. Autentíquese con Authorization: Bearer nxa_live_... (consulte Claves de API).

Nota. Los ejemplos de abajo usan valores inventados a modo de ilustración. Sustituya la clave y los ids por los suyos.

Puntos de conexión que puede usar una clave

Enumerar agentes

curl https://phynxa.com/api/agents -H "Authorization: Bearer nxa_live_YOUR_KEY"

Devuelve un array JSON. Un elemento (abreviado):

{
  "id": "c2997c6f-9d1c-41bb-9ba7-f2e3c6e2a648",
  "name": "Reception Marina",
  "description": "",
  "language": "en",
  "model": "openai:gpt-4o-mini",
  "stt_provider": "deepgram-nova-3",
  "tts_provider": "cartesia",
  "voice": "a0e99841-438c-4a64-b679-ae501e7d6091",
  "greeting": "Hello! How can I help you today?",
  "temperature": 0.6,
  "can_end_call": true,
  "can_transfer_call": false,
  "transfer_number": "",
  "call_direction": "inbound",
  "phone_number": "",
  "active": true,
  "webhook_id": "",
  "timezone": "UTC",
  "created_at": "2026-10-10T23:27:33.841629+00:00",
  "updated_at": "2026-10-10T23:27:33.841629+00:00"
}

active es true para un agente publicado. Algunos indicadores, como capture_enabled, se devuelven como 0 o 1.

Crear y modificar un agente

curl -X POST https://phynxa.com/api/agents \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "API example agent", "language": "en"}'

Crear admite name (obligatorio) y, opcionalmente, language (en, ur, hi, ar, fr, es, zh), timezone, template_id, business_name y template_inputs. La respuesta es el nuevo agente. En el plan Free el agente nuevo tiene active: false.

Modifique campos con PATCH. Solo cambia lo que envía, y los campos desconocidos se rechazan para que una errata no pase en silencio:

curl -X PATCH https://phynxa.com/api/agents/AGENT_ID \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"greeting": "Thanks for calling Acme. How can I help?", "temperature": 0.4}'

Los campos que puede modificar incluyen name, description, model (como provider:model, por ejemplo openai:gpt-4.1), system_prompt, greeting, stt_provider, tts_provider, voice, language, temperature, max_turn_seconds, idle_prompts, idle_message, can_end_call, can_transfer_call, transfer_number, phone_number, call_direction, webhook_id, capture_form_id, capture_enabled, call_summary_enabled, timezone y active (publicar o despublicar). DELETE /agents/{id} responde 204.

Realizar una llamada saliente

curl -X POST https://phynxa.com/api/calls/outbound \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID", "to_number": "+14155552671"}'

Si tiene éxito, recibe 202:

{ "call_sid": "CA0123456789abcdef0123456789abcdef", "to": "+14155552671" }

El agente debe estar publicado y configurado como Outbound o Inbound / Outbound, y su espacio de trabajo necesita Twilio conectado. Errores:

Leer llamadas y transcripciones

GET /calls devuelve las llamadas terminadas, las más recientes primero, hasta 200. Cada una tiene id, agent_id, agent_name, started_at, ended_at, seconds, turns, direction, from_number, to_number, outcome, cost_usd y los campos de revisión summary, intent, sentiment, outcome_label, score, action_items y entities, además del desglose del coste (llm_cost_usd, stt_cost_usd, tts_cost_usd, etc.).

GET /calls/{id} devuelve una llamada con su transcript y sus tool_calls. GET /calls/{id}/transcript devuelve solo las líneas, cada una con role (user o assistant), text y at.

GET /stats devuelve totales:

{
  "agents": 4,
  "active_agents": 3,
  "calls": 29,
  "minutes": 64.28,
  "avg_call_seconds": 133.0,
  "total_cost": 1.59,
  "avg_cost_per_call": 0.0548,
  "p95_latency_ms": 0.0
}

Contactos

curl -X POST https://phynxa.com/api/contacts \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sara K.", "phone_number": "+971501234567", "country_code": "AE", "timezone": "Asia/Dubai", "status": "lead"}'

status es lead, customer, engaged o blocked. POST /contacts/import admite {"contacts": [ ... ]} de hasta 5.000 filas con name, phone_number, country_code y timezone.

Webhooks

POST /webhooks con {"name": "CRM sync"} crea uno; fije sus datos con PATCH /webhooks/{id}, que admite url, method, headers, secret, events, payload_fields, active, timeout_secs (hasta 60) y retries (de 1 a 5):

curl -X PATCH https://phynxa.com/api/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer nxa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/hooks/calls", "secret": "whsec_your_secret", "payload_fields": ["call", "review", "transcript"]}'

POST /webhooks/{id}/test envía un ejemplo y devuelve {"ok": true, "status_code": 200, "error": "", "duration_ms": 2}. El secreto nunca se devuelve: las respuestas muestran secret_configured.

Errores

Los errores son JSON con un detail.

Un error de validación enumera cada problema:

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "name"],
      "msg": "String should have at least 1 character",
      "input": "",
      "ctx": { "min_length": 1 }
    }
  ]
}

Límites de frecuencia

Prueba

Ejecute el ejemplo de enumerar agentes. Después cree un agente y elimínelo de nuevo.

Resultado esperado

Respuestas JSON como las mostradas, y 204 al eliminar.

Solución de problemas

• 401 en todas las solicitudes. Revise el prefijo Bearer y que la clave no se haya revocado.
• 422 «Extra inputs are not permitted». El nombre de un campo está mal escrito.
• 429. Vaya más despacio y reintente tras una pausa.

Guías relacionadas

• Claves de API
• Webhooks