> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # External API design ## Overview External engineering teams often build or adapt APIs so API tools can retrieve data, update records, or initiate workflows. These guidelines describe how to design APIs that integrate smoothly with API tools and deliver consistent, reliable behavior in production environments. #### Quick summary API tools interact with external APIs for every operation. The table below highlights which parts of an integration are required for compatibility and which are recommended to ensure consistent performance under automation, with links to relevant sections. | Category | Topic | **Requirements** | **Recommendations** | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **[Core protocol and data format](#core-protocol-and-data-format)** | [Supported data formats](#supported-data-formats) | Responses must return data in a format supported by API tools (JSON, XML, or URL-encoded) | For example, when using JSON, include explicit `Content-Type` and `Accept` headers | | | [Request and response structure](#request-and-response-structure) | — | Use deterministic responses, evolve schemas additively, avoid deep or ambiguous nesting | | | [Timestamps](#timestamps) | — | Use ISO-8601 UTC timestamps for clarity | | **[Authentication](#authentication)** | [Static bearer tokens](#static-bearer-tokens-server-to-server) | Accept `Authorization: Bearer ` | Use scoped tokens, rotate them safely, grant only required permissions | | | [OAuth 2.0 authorization code](#oauth-20-authorization-code-per-user-access) | Provide Authorization URL, Token URL, PKCE or authorization code flow, and refresh tokens | Support PKCE, issue refresh tokens, use short-lived access tokens | | **[API behavior](#api-behavior)** | [REST-style endpoints](#rest-style-endpoints) | Follow standard HTTP verb behavior | — | | | [Versioning](#versioning) | — | Use URI-based versioning, introduce breaking changes only in new versions | | | [Pagination](#pagination) | — | API tools does not support paginated retrieval across multiple requests; endpoints must return all required data in a single response | | **[Error handling](#error-handling)** | [HTTP status codes](#http-status-codes) | Use appropriate HTTP status codes (2xx, 4xx, 5xx) | — | | | [Error responses](#error-responses) | Provide predictable error responses (for example, JSON) | Include structured error fields (e.g., code, message, field) | | **[Rate limits](#rate-limits)** | | — | Return standard rate-limit responses (such as `429`) to clearly indicate throttling | | **[Security](#security)** | [Webhooks (unsupported)](#webhooks-not-supported) | — | API tools do not support webhook-style endpoints | | **[Observability and debugging](#observability-and-debugging)** | | — | Support request ID correlation and log stable, non-sensitive identifiers | | **[Example endpoint](#example-endpoint)** | | — | Follow predictable structures and clearly document request and response formats | ## Core protocol and data format API tools communicate with your external APIs using standard HTTP requests. The following guidelines describe the formats and conventions API tools expect or work best with. ### HTTPS API tools call external APIs over standard HTTPS. Endpoints must be reachable over the internet so API tools can send requests. ### Supported data formats API tools can work with responses returned in [supported data formats](/docs/automation/tools/api-tools/api-tool-control#this-api-uses), including **JSON**, **XML**, and **URL-encoded** data. In practice, API tools commonly send and receive JSON payloads. When using JSON, include standard HTTP headers that clearly identify the response format: | Header | Description | | ----------------------------------------------- | ------------------------------------------------------------ | | `Content-Type: application/json; charset=utf-8` | Indicates that the response body is JSON encoded in UTF-8 | | `Accept: application/json` | Indicates that the client expects the response to be in JSON | These headers help ensure consistent parsing and predictable behavior when JSON is used. ### Request and response structure While API tools can work with a variety of JSON structures, the following practices help ensure stable and predictable integrations: * **Deterministic responses**: The same request should return responses with consistent field names and types. * **Stable schema**: When introducing changes to your API, add fields rather than removing or renaming them. * **Clear structure**: Avoid unnecessarily deep or ambiguous nesting, which can make API tool output mapping harder. > **Note** > > These are recommendations based on common REST API design patterns, not requirements about how your API must be implemented internally. ### Timestamps If your API returns timestamps, using a standard format such as ISO-8601 UTC is recommended. For example: `2025-12-11T16:40:00Z`. This format is widely supported across tools and makes it easier for API tools to pass timestamp data to downstream systems. ## Authentication API tools support several authentication methods when calling your external APIs. This section outlines the authentication models available and the typical expectations for each approach. ### Static bearer tokens (server-to-server) API tools must include a static bearer token when calling your API, using the standard HTTP header: `Authorization: Bearer`. * It's best to use scoped, long-lived tokens or rotate them safely. * This model is appropriate for simple, system-level integrations that do not require per-user authentication. ### OAuth 2.0 authorization code (per-user access) If your API needs to act on behalf of authenticated users, API tools can complete an OAuth 2.0 authorization code flow. * Your system must provide: * Authorization URL * Token URL * Proof Key for Code Exchange (PKCE) or standard authorization code support * Refresh tokens * Recommendations: * Support PKCE where possible * Provide refresh tokens for long-running sessions * Use short-lived access tokens for added security ## API behavior The following practices reflect widely adopted REST API patterns and can help ensure predictable and reliable integrations when API tools call your external APIs. ### REST-style endpoints Standard HTTP methods should follow widely adopted REST semantics: | Method | Description | | ------------- | -------------------------------------------- | | `GET` | Retrieves data without modifying state | | `POST` | Creates a new resource or triggers an action | | `PUT`/`PATCH` | Updates an existing resource | | `DELETE` | Removes a resource | ### Versioning Using versioned endpoints helps maintain long-term compatibility, especially as your API evolves. A common pattern is to include a version in the URL, for example: * `/api/v1/orders` * `/api/v1/customers` Adding new fields over time maintains compatibility, while breaking changes are typically introduced in a new version (v2, v3, etc.). This approach provides stability for any client consuming your API, including API tools. ### Pagination API tools **do not automatically retrieve additional pages of results**. If an API response is paginated across multiple pages, API tools process only the data returned in a single request. When building endpoints intended for use with API tools, ensure that each request returns all data required for the API tool to complete, otherwise only the first page of a paginated response will be processed. ### Idempotency Designing APIs to be stateless and idempotent helps ensure reliable behavior when used with API tools. If the same request is sent multiple times (for example, due to retries after a network interruption), the operation should be processed only once and should not result in duplicate records or repeated side effects. API tools **do not support idempotency keys**, so idempotent behavior must be handled through API design. ## Error handling When designing error responses, following common API conventions can make your API easier for automated systems (including API tools) to work with. ### HTTP status codes Using HTTP status codes consistently helps clients understand how to react: * **2xx**: Request succeeded * **4xx**: Request was invalid or unauthorized * **5xx**: Server encountered an unexpected error > **Tip** > > `5xx` errors typically reflect temporary server-side issues where retrying the request may succeed. By contrast, `4xx` errors indicate a problem with the request itself (such as invalid data or missing authorization), so resending the same request will produce the same result. ### Error responses Providing predictable, machine-readable error responses makes it easier for clients to handle failures programmatically. #### Sample response **`JSON`** ```json JSON { "error": { "code": "INVALID_INPUT", "message": "Email format is invalid", "field": "email" } } ``` > **Note** > > This is a suggested format based on common REST API practices; your API may use a different structure as long as the fields are consistent and clearly documented. ## Rate limits When an API used with API tools returns a rate-limited response, the request is not retried. API tools process each request once, and a rate-limited response causes the API tool to be marked as failed. If your API applies rate limits, returning standard HTTP rate-limit responses (such as `429 Too Many Requests`) can help clearly indicate that a request was rejected due to rate limiting. This information is useful for understanding and diagnosing API tool failures, but **retry or backoff behavior must be handled outside of API tools** (for example, within the API itself). ## Security The following security practices are widely used across modern REST APIs and help ensure safe interactions when external systems call your API. * Always use HTTPS to encrypt requests and responses in transit. * Avoid exposing sensitive personally identifiable information (PII) in responses. * Never include secrets (such as API keys or tokens) in error messages or logs. * If your API requires IP allowlisting, provide static outbound IP ranges so external systems can be granted access without interruption. ### Webhooks (not supported) API tools do not support webhook-style endpoints and cannot receive incoming webhook requests. > **Tip** > > If your broader API design includes webhooks outside of API tools, follow standard webhook security practices, such as signing payloads and documenting verification steps. ## Observability and debugging In integrations that involve multiple systems, problems can originate in several places. Good observability, such as shared request IDs and consistent logging, helps teams quickly pinpoint whether an issue occurred in the client, the API, or downstream services. ### Request ID correlation Automated systems may include a request identifier in outbound calls, such as: `X-Request-Id: `. Echoing this value in your response helps correlate related events across services. This practice is widely adopted in distributed systems and does not imply any specific implementation on the caller's side. ### Logging When logging requests or responses, consider the following: * Do not log full tokens, secrets, or sensitive user data. * Log stable identifiers (such as resource IDs), timestamps, and any request IDs provided by the client. * Ensure logs contain enough information to trace behavior without exposing sensitive data. These are general logging recommendations suitable for any API integration. ## Example endpoint The following example illustrates common REST API patterns. It uses `JSON` for illustration purposes. XML and URL-encoded formats are also supported. Your API may return responses in other formats as long as they are predictable and documented. #### Sample request ``` POST /api/v1/orders Authorization: Bearer {Token} Content-Type: application/json Accept: application/json ``` #### Request body **`JSON`** ```json JSON { "customer_id": "cus_123", "items": [{ "sku": "abc", "qty": 2 }] } ``` #### Success response **`JSON`** ```json JSON { "id": "ord_789", "status": "created", "created_at": "2025-12-11T16:40:00Z" } ``` #### Error response **`JSON`** ```json JSON { "error": { "code": "INVALID_SKU", "message": "Invalid SKU" } } ``` ## Related features Explore complementary resources for building and managing API tools. * [API tools overview](/docs/automation/tools/api-tools): Learn what API tools are and how they connect your AI Agent to external systems. * [API tool control](/docs/automation/tools/api-tools/api-tool-control): Configure and manage API tools in the Ada Dashboard. * [Token configuration](/docs/automation/tools/api-tools/token-configuration): Securely store authentication tokens for API calls. * [API overview](/reference/introduction/overview): Explore Ada's own APIs for building integrations. * [Authentication](/reference/introduction/authentication): Understand how to authenticate with Ada's APIs. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).