Platform API

FYAI exposes four public REST APIs. They speak JSON over HTTPS and share one authentication scheme. This page is the reference; for worked examples see Common API tasks.

Hosts and what each owns

Send each request to the service that owns the resource. Paths below are relative to that service's base URL.

Agent API — https://agent.fyai.co.nz

Area	Paths
Agents, and running them	/agents, /agents/search, /agents/{id}, /agents/{id}/run, /agents/{id}/run-async, /agents/run-async/{execution_id}, /agents/{id}/readiness, /agents/{id}/functions, /agents/{id}/sub-agents, /agents/{id}/identity
Context prompts and request contexts	/agents/context-prompts, /agents/request-contexts
Teams	/team-configurations
Models (LLM configs)	/llmconfigs, /llmconfigs/{id}/resolved, /platform-models
Functions (tools)	/functions
Chat	/chat/start, /chat/sessions, /chat/{id}, /chat/{id}/conversations, /chat/{id}/state, /chat/{id}/end, /chat/{id}/approval, /chat/{id}/handoff, /chat/history
Workflow execution	/workflows/execute, /workflows/{id}/validate, /workflows/{id}/nodes/{node_id}/run, /workflows/missions/{mission_id}/approve, /workflows/missions/{mission_id}/node-approvals/{approval_id}/resolve, /workflows/{id}/test-nodes, /workflows/{id}/run_all_tests
Testing	/tests/agents/{id}/test-cases, /tests/teams/{id}/test-cases, /tests/test-cases/{id}/run, /tests/metrics, /tests/coverage
Observability and usage	/observability/agents/{id}/summary, /observability/teams/{id}/summary, /usage/summary, /usage/daily, /usage/by-agent, /usage/by-project, /risk-registry
Event sources	/event-sources
Promotions and environment deploys	/promotions/analyze, /promotions/execute, /promotions/history, /environments/{id}/deploy
Templates	/agent-templates, /team-templates, /function-templates, /llmconfig-templates, /templates/instantiate
Change history and killswitch	/history/{entity_type}/{entity_id}, /killswitch/{entity_type}/{entity_id}
GitHub App connection	/github/installation/start
Live events	wss://agent.fyai.co.nz/ws/events

The agent service also hosts the governance APIs behind Governance in the web app (AI systems, policy, control library, assurance pack, alerts). See Governance.

Catalog API — https://catalog.fyai.co.nz

Area	Paths
Workflow definitions	/workflows, /workflows/{id}, /workflows/validate, /workflows/schema, /workflows/{id}/instantiate, /workflows/{id}/run-state, /workflows/{id}/eval-results
Workflow schedules and metrics	/workflow-schedules/, /metrics/workflows, /metrics/workflows/{id}
Missions (workflow runs)	/missions, /missions/{id}, /missions/{id}/steps, /missions/node-approvals/pending, /mission-configurations/
Programs	/programs, /programs/{id}/phases, /phases/{phase_id}/activities, /programs/{id}/phases/{phase_id}/run, /programs/checkpoints/{id}/resolve, /programs/{id}/documents, /programs/{id}/knowledge
Knowledge	/knowledge-bases, /knowledge-bases/{id}/readiness, /knowledge-documents, /knowledge-documents/ingest-text, /knowledge-documents/ingest-url, /knowledge-documents/ingest-git, /knowledge-documents/ingest-confluence, /knowledge-documents/ingest-manifest, /knowledge-documents/upload, /knowledge-documents/ingest-jobs/{job_id}, /knowledge-documents/search
Agent memory	/episodic-memories, /episodic-memories/search, /episodic-memories/observe
Data sources	/data-sources, /data-sources/connectors, /data-sources/{id}/data, /data-sources/{id}/refresh, /data-source-templates
Dashboards, elements and manifests	/dashboards, /elements, /manifests, /manifests/by-name/{name}, and their -templates
Execution environments	/execution-environments, /execution-environments/{id}/status, /execution-environments/{id}/tools
Webhooks	/webhooks, /webhooks/{id}/logs, /webhooks/{id}/regenerate-secret
Repositories	/repositories, /github/installations
Marketplace stacks	/stacks
Templates and history	/workflow-templates, /templates/instantiate, /history/{entity_type}/{entity_id}, /killswitch/{entity_type}/{entity_id}

Integration API — https://integration.fyai.co.nz

Area	Paths
Integrations	/integrations, /integrations/{id}, /integrations/search, /integrations/shared, /integrations/schema
Secrets	/integrations/{id}/secrets, /integrations/{id}/secrets/metadata, /integrations/{id}/secrets/by_path
Access and sharing	/integrations/{id}/access, /access
Connected accounts	/user-connections
Templates	/integration-templates, /templates/instantiate

Auth API — https://auth.fyai.co.nz

Area	Paths
API keys	/api-keys, /api-keys/validate, /api-keys/current
Service account tokens	/service-accounts/token
Your user, organisations and projects	/users/me, /organizations, /projects

Request conventions

• JSON in, JSON out. Send Content-Type: application/json on requests with a body. The only exception is file upload to a knowledge base (POST /knowledge-documents/upload), which is multipart/form-data.
• Scope comes from the credential. You never send a tenant or project ID. Creating a resource puts it in the credential's project; listing returns only that project's resources. Fields such as tenant_id and project_code appear in responses but are ignored or rejected on input.
• IDs are integers for most entities. Async agent executions and ingest jobs use string IDs.
• PATCH is a partial update. Send only the fields you want to change. A few resources (workflow definitions, workflow schedules, mission configurations) are updated with PUT.
• Names or IDs. Where a field links to another entity, some endpoints accept either. For example, an agent's llm_config can be the LLM config's ID or its name.
• Listing and searching. Agent-service lists take skip and limit (default 100). Agents, teams, functions and LLM configs also have a /search endpoint taking field, query and fuzzy (default true). Catalog and integration searches are POST .../search with a JSON body.

Set a normal HTTP client User-Agent. The hosts sit behind Cloudflare, which can block some default library user agents (Cloudflare error 1010).

Long-running operations

The hosts sit behind a proxy that closes idle connections after about 100 seconds, so anything that might take longer runs asynchronously:

Operation	Start	Track
Agent run	POST /agents/{id}/run-async → execution_id	GET /agents/run-async/{execution_id} until status is completed or error. Results are kept for about two hours after the run finishes.
Workflow run	Create a mission, then POST /workflows/execute	GET https://catalog.fyai.co.nz/missions/{mission_id} until phase is completed or failed
Chat session started from code	POST /chat/start with "start_run": true	GET /chat/{id} (run_alive, display_state) and GET /chat/{id}/conversations
URL, git, Confluence or file ingestion	POST /knowledge-documents/ingest-url (and the others) → job_id	GET /knowledge-documents/ingest-jobs/{job_id} until status is done or error
Program activity or phase	POST .../activities/{id}/run or .../phases/{id}/run	GET .../activities/{id}/runs

POST /agents/{id}/run is the synchronous version of an agent run. Use it only for runs you're confident finish well inside 100 seconds. See Common API tasks for each flow end to end.

Errors

Errors return a JSON body with a detail field.

Status	Meaning
400	The request is invalid, for example a required field is missing or a value isn't allowed.
401	No credential, or the credential was rejected. See Authentication.
402	Your organisation can't run or change anything right now: its token allowance is used up with no credit left, its trial has ended, it has been paused, or its plan doesn't include bring-your-own-key models. See Usage and billing.
403	The credential's access level is too low, or it may not launch this agent or workflow.
404	The resource doesn't exist in the credential's project. Resources in other projects usually return 404 rather than 403, so their existence isn't revealed.
409	A conflict, for example connecting a repository that's already connected to the project.
413	An uploaded file is too large. Knowledge-base uploads are limited to 50 MB.
422	The body failed validation. detail lists the fields.
423	The agent, workflow or other entity has been stopped with the killswitch and can't start new runs.
429	Rate limit exceeded. Wait and retry.
503	A dependency was temporarily unavailable, for example Authentication service unavailable, please retry. Retry with backoff.

Rate limits

The platform doesn't apply a blanket per-key request limit. These endpoints have their own limits, and return 429 when exceeded:

Endpoint	Limit
DELETE /agents/{id} (agent API)	20 a minute
DELETE /llmconfigs/{id} (agent API)	20 a minute
POST /integrations/{id}/secrets (integration API)	60 a minute
POST /service-accounts/token (auth API)	30 a minute per IP address
Inbound webhook deliveries, POST /webhooks/receive/{token} (catalog API)	120 a minute per source IP address

Separately, model providers enforce their own rate limits. When a model is rate limited mid-run, the platform waits and retries inside the run rather than failing it immediately, so a run can take longer than usual.

Live events stream

The agent API streams events about your project over a WebSocket. The web app uses it to refresh lists and show activity as things change.

wss://agent.fyai.co.nz/ws/events

Authenticate with an X-API-Key or Authorization: Bearer header when you open the connection (see WebSocket authentication). Passing ?api_key= or ?token= in the URL still works but is deprecated, because URLs leak into logs. The stream is scoped to the credential's organisation and project.

After connecting you receive:

{ "type": "connected", "tenant_id": "...", "project_code": "..." }

Then one message per event:

{
  "type": "platform_event",
  "event_id": "…",
  "event_type": "entity.updated",
  "source": "agentapi",
  "payload": {
    "entity_type": "agent",
    "entity_id": 42,
    "entity_name": "Support Agent",
    "action": "updated",
    "actor": { "id": "…", "name": "…" }
  },
  "timestamp": "2026-10-04T01:23:45.678901+00:00",
  "metadata": {}
}

event_type	When
entity.created, entity.updated, entity.deleted	An agent, team, function, LLM config, dashboard, workflow, program or other entity changed. payload.action is created, updated or deleted, or a more specific action such as rolled_back, killswitch_on or killswitch_off.
chat.session.updated	One of your own chat sessions changed. Only sent to the session's owner.
event_source.connected, event_source.error	An event source connected or failed.

Send the text ping at any time to get {"type": "pong"} back, which is useful as a keep-alive. Events aren't replayed: if you disconnect, re-read the resources you care about when you reconnect.