aethexDocs
Dashboard

API Reference

Integrations

Connect third-party tools to your agents: connect a provider, grant it to agents, then manage or disconnect it. Every endpoint is scoped to your account by your API key; credentials are validated against the vendor, stored encrypted, and never returned.

Base URL
https://api.aethexai.com/api/v1
Endpoints
15
Scopes
integrations:readintegrations:writeagents:readagents:write
GET/integrations/providers

The catalog of connectable providers and their family.

List providers

Returns every provider you can connect, each with the integration family it belongs to (crm, calendar, automation). Requires integrations:read.

POST/integrations

Validate a credential against the vendor and store it encrypted.

Connect an integration

Connects a third-party integration for your account. Aethex validates the credential against the vendor before persisting it encrypted; the credential never appears in any response. Re-connecting a provider replaces your previous active connection for it. Per-provider fields go in config (for example an Odoo database and odoo_major_version). n8n takes base_url and, optionally, webhook_secret; its workflows are bound afterwards with PUT /integrations/{id}/n8n/tools. Requires integrations:write.

Request body

10
  • providerstringrequired

    The provider key, for example odoo, hubspot, calendly, or http_list (a custom list source: base_url is your records endpoint and access_token the secret it checks). See GET /integrations/providers.

  • access_tokenstringrequired

    The vendor credential (an API key, private-app token, or personal access token). Write-only; never returned.

  • auth_typestringoptional

    api_key (default) or oauth2. Odoo requires api_key.

  • base_urlstringoptional

    The vendor instance URL, for providers that are self-hosted or per-tenant. Odoo and n8n require it, public HTTPS only.

  • configobjectoptional

    Non-secret per-provider settings and the optional enabled_tools narrowing. Odoo takes database, odoo_major_version, and username (Odoo 16 to 18). n8n takes only webhook_base_url.

  • webhook_secretstringoptional

    n8n only. The secret Aethex presents in the X-Aethex-Token header when it calls your workflows, 16 to 512 characters. Optional: without it Aethex creates its own Header Auth credential in your n8n and generates the secret. Write-only; never returned.

  • agentsarrayoptional

    Agents allowed to use the connection, each with read or write. Omit for none; nothing is inherited from a replaced connection.

  • display_namestringoptional

    A label for the connection shown in the portal.

  • refresh_tokenstringoptional

    The OAuth renewal token, when you bring your own. Write-only.

  • expires_inintegeroptional

    Seconds until the access token expires, for the renewal path.

Errors

5
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

422Unprocessable

Unknown provider, a missing or malformed field, or the vendor rejected the credential.

Read the message; it names the field or the vendor error.

409Conflict

A concurrent request already created or changed this connection or its grants.

Re-read the connection and retry.

429Too Many Requests

The per-account rate limit was exceeded: 10 connects per minute, or 35 n8n discovery and bind requests per minute.

Retry after the Retry-After interval.

503Service Unavailable

The vendor API was unreachable, the encryption key is not configured, or the rate limiter is offline.

Transient; retry shortly.

POST/integrations/:provider/authorize

Get the vendor consent URL for an OAuth provider.

Start an OAuth connect

Returns the vendor consent URL for a provider that connects over OAuth. Send the customer's browser to authorize_url; the vendor redirects back to Aethex, which finishes the connection. Providers that take a direct credential use POST /integrations instead. Requires integrations:write.

Path & Query

1
  • providerstringrequired

    The OAuth provider key, for example google_calendar.

Errors

2
422Unprocessable

Unknown provider, a missing or malformed field, or the vendor rejected the credential.

Read the message; it names the field or the vendor error.

503Service Unavailable

The vendor API was unreachable, the encryption key is not configured, or the rate limiter is offline.

Transient; retry shortly.

GET/integrations

Your account's integration connections.

List connections

Returns your active integration connections with their agent grants, paginated. Requires integrations:read.

Path & Query

2
  • offsetintegeroptional

    Number of connections to skip. Defaults to 0.

  • limitintegeroptional

    Page size, 1 to 200. Defaults to 50.

GET/integrations/:connection_id

One connection by id.

Get a connection

Returns a single connection and its agent grants. An n8n connection also carries credential (the Header Auth credential Aethex presents, never its value), tools and post_call_workflow_id. Requires integrations:read.

Path & Query

1
  • connection_idstringrequired

    The connection id.

Errors

1
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

GET/integrations/:connection_id/agents

Which agents may use this connection.

List agent grants

Returns the agents allowed to use the connection and each one's access level. An empty list means the connection reaches no call. Requires integrations:read.

Path & Query

1
  • connection_idstringrequired

    The connection id.

Errors

1
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

PUT/integrations/:connection_id/agents

Replace the set of agents allowed to use this connection.

Set agent grants

Replaces the whole set of agent grants: send every agent that should keep access, not just the one you are adding. An empty list revokes every grant. Requires integrations:write.

Path & Query

1
  • connection_idstringrequired

    The connection id.

Request body

1
  • agentsarrayrequired

    The complete list of grants, each an agent_id and an access of read or write.

Errors

2
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

409Conflict

A concurrent request already created or changed this connection or its grants.

Re-read the connection and retry.

DELETE/integrations/:connection_id

Revoke a connection.

Disconnect an integration

Revokes an integration connection. Idempotent: returns 204 whether the connection was active, already revoked, or never present on your account. Requires integrations:write.

Path & Query

1
  • connection_idstringrequired

    The connection id.

GET/integrations/:connection_id/n8n/workflows

Which of your n8n workflows Aethex can call, and how to fix the ones it cannot.

List n8n workflows

Reads the n8n instance behind the connection and returns every workflow that has a Webhook trigger, judged on its published version, with the derived production webhook_url, the trigger's methods and authentication, the credential it uses, a ready verdict and, when not ready, issues with the matching fixes in n8n terms. bound_as is the tool name the workflow is already bound to. Nothing is written; up to 1,000 workflows are walked and truncated flags the rest. Rate limited to 35 requests per minute per account. Requires integrations:read. See the n8n guide.

Path & Query

1
  • connection_idstringrequired

    The connection id.

Errors

5
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

409Conflict

A concurrent request already created or changed this connection or its grants.

Re-read the connection and retry.

422Unprocessable

Unknown provider, a missing or malformed field, or the vendor rejected the credential.

Read the message; it names the field or the vendor error.

429Too Many Requests

The per-account rate limit was exceeded: 10 connects per minute, or 35 n8n discovery and bind requests per minute.

Retry after the Retry-After interval.

503Service Unavailable

The vendor API was unreachable, the encryption key is not configured, or the rate limiter is offline.

Transient; retry shortly.

PUT/integrations/:connection_id/n8n/tools

Declare which workflows agents may call, and which one receives the call report.

Bind n8n workflows as tools

Replaces the whole set of tools on an n8n connection. Each entry names a workflow_id, the tool_name the model calls, a description, a JSON Schema parameters object and a writes flag; post_call_workflow_id names the workflow that receives the call.ended report. Every workflow is re-read from n8n and must be ready: any that is not fails the request with 422 listing workflow_id, issues and fixes, and nothing is stored. [] unbinds everything. Agent grants are untouched. Requires integrations:write.

Path & Query

1
  • connection_idstringrequired

    The connection id.

Request body

2
  • workflowsarrayrequired

    Up to 20 bindings. Each has workflow_id (the n8n id), tool_name (1 to 64 characters of letters, digits, _ or -, unique, not a reserved pipeline name), description (plain text, up to 300 characters), parameters (a JSON Schema object of at most 8 KiB whose required names are all declared in properties) and writes (defaults to true; false lets agents with a read grant see the tool).

  • post_call_workflow_idstringoptional

    The workflow that receives the call.ended report for agents with a write grant. Must be ready like any bound workflow. Omit or send null for none.

Errors

5
404Not found

The connection id, or an agent id in agents, is not on your account or was deleted.

Check the id. A 404 on a write is deliberate so it cannot confirm another account's id.

409Conflict

A concurrent request already created or changed this connection or its grants.

Re-read the connection and retry.

422Unprocessable

A workflow is not ready (the detail lists workflows, each with issues and fixes), a tool_name is reserved or malformed, or parameters is not an object schema.

Apply the fixes in n8n, then re-send the whole list. Nothing was stored.

429Too Many Requests

The per-account rate limit was exceeded: 10 connects per minute, or 35 n8n discovery and bind requests per minute.

Retry after the Retry-After interval.

503Service Unavailable

The vendor API was unreachable, the encryption key is not configured, or the rate limiter is offline.

Transient; retry shortly.

POST/integrations/surveymonkey

Turn a public SurveyMonkey link into a voice agent that calls participants and reads the survey.

Create a SurveyMonkey survey agent

Provisions a voice agent that phones a participant and asks a SurveyMonkey survey's questions, then maps the answers back onto the form after the call. Question discovery runs asynchronously, so the agent is returned in provisioning status and becomes active (dialable) once its script is written. From then on it behaves like any agent: place calls with POST /calls/trigger and read results from the call transcript. Returns the full Agent object; see the Agents API reference for every field.

Request body

4
  • survey_urlstringrequired

    Public SurveyMonkey survey link (https). Must be a surveymonkey.com URL.

  • voice_idstringrequired

    Voice the agent speaks with. Must be one of your voices from GET /voices.

  • languagestringrequired

    Call language: english or french.

  • namestringoptional

    Optional agent name (max 255 characters). Defaults to the name SurveyMonkey agent.

Errors

2
422Invalid request

survey_url is not an https surveymonkey.com link, language is missing or not english/french, or voice_id is not one of your voices.

Send a public surveymonkey.com survey link, a supported language, and a voice_id returned by GET /voices.

503Provisioning unavailable

The survey provisioning queue is temporarily unavailable, so the agent's script could not be scheduled.

Retry the request in a few moments. No agent is created when this error is returned.

GET/integrations/:connection_id/imports/entities

What kinds of record this connection can be read from.

List importable record types

The first call when building an import: it asks the connected system what it holds and returns each record type with the label that system uses for it. Available on Odoo connections. Import calls share a rate limit, so walk this once and cache the result rather than calling it per screen.

Path & Query

1
  • connection_idstring (uuid)required

    The connection's id, from POST /integrations or the connections list.

Errors

2
422Import unavailable

The connection's stored credentials no longer work, so the source system refused us.

Reconnect the integration with fresh credentials, then retry.

429Too many import calls

Import calls share a per-workspace rate limit, and this one exceeded it.

Honour Retry-After, and cache entity and field lists rather than re-reading them per screen.

GET/integrations/:connection_id/imports/fields

The fields on one record type, plus the phone regions you can default to.

List a record type's fields

Given a record type, returns its fields so you can choose which to bring across and which hold phone numbers. phone_regions lists every region code the platform can parse a local number against — pair it with default_country when the source system stores numbers without a country code.

Path & Query

2
  • connection_idstring (uuid)required

    The connection's id, from POST /integrations or the connections list.

  • entitystringrequired

    The record type to read, named as the connected system names it — for example res.partner for Odoo contacts.

Errors

2
422Import unavailable

The record type is not available on this connection, or a field or filter it names does not exist.

Re-read the entity and field lists for this connection and send names from those responses.

429Too many import calls

Import calls share a per-workspace rate limit, and this one exceeded it.

Honour Retry-After, and cache entity and field lists rather than re-reading them per screen.

POST/integrations/:connection_id/imports/preview

Count what a selection would bring in before you read any of it.

Preview an import

Runs the selection without starting an import: total is how many records the source holds, sample counts how the first page of numbers parsed (valid, invalid, missing), and rows shows those records so you can check the mapping. Each row carries the number as stored (raw_phone), as parsed (phone), and the verdict (phone_status). Call this before paging, so a bad mapping costs one request rather than a full walk.

Path & Query

1
  • connection_idstring (uuid)required

    The connection's id, from POST /integrations or the connections list.

Request body

5
  • entitystringrequired

    The record type to read, named as the connected system names it — for example res.partner for Odoo contacts.

  • fieldsstring[]required

    The fields to bring back, named as the connected system names them.

  • phone_sourcesstring[]required

    Which of those fields hold phone numbers, in priority order. The first one that parses wins.

  • scopestringoptional

    An optional filter in the source system's own query syntax, to narrow which records match.

  • default_countrystringoptional

    Two-letter region code used to parse numbers stored without a country code, for example GH. Pick one from phone_regions.

Errors

2
422Import unavailable

The record type is not available on this connection, or a field or filter it names does not exist.

Re-read the entity and field lists for this connection and send names from those responses.

429Too many import calls

Import calls share a per-workspace rate limit, and this one exceeded it.

Honour Retry-After, and cache entity and field lists rather than re-reading them per screen.

POST/integrations/:connection_id/imports/page

Walk the matching records in pages, cursor by cursor.

Read a page of records

Reads the records a preview counted, in pages of up to 500, ordered by the source's own id. Pass the previous response's next_after_id back as after_id to get the next page, and stop when next_after_id is null. Keep entity, fields, phone_sources and scope identical across the walk — changing them mid-walk restarts the cursor.

Path & Query

1
  • connection_idstring (uuid)required

    The connection's id, from POST /integrations or the connections list.

Request body

7
  • entitystringrequired

    The record type to read, named as the connected system names it — for example res.partner for Odoo contacts.

  • fieldsstring[]required

    The fields to bring back, named as the connected system names them.

  • phone_sourcesstring[]required

    Which of those fields hold phone numbers, in priority order. The first one that parses wins.

  • scopestringoptional

    An optional filter in the source system's own query syntax, to narrow which records match.

  • default_countrystringoptional

    Two-letter region code used to parse numbers stored without a country code, for example GH. Pick one from phone_regions.

  • after_idstringoptional

    The previous page's next_after_id. Omit for the first page.

  • limitintegeroptional

    Records per page, up to 500. Defaults to 500.

Errors

2
422Import unavailable

The record type is not available on this connection, or a field or filter it names does not exist.

Re-read the entity and field lists for this connection and send names from those responses.

429Too many import calls

Import calls share a per-workspace rate limit, and this one exceeded it.

Honour Retry-After, and cache entity and field lists rather than re-reading them per screen.