API Endpoints

API Endpoints give your tenant HTTPS endpoints that run an Action Flow synchronously: the caller sends a request, the Action Flow runs while the request waits, and the response the flow composes is returned to the caller. This turns an Action Flow into a real API — for example validating and registering an invoice sent by an ERP, looking up enriched data, or converting a document and returning the result in the same call.

Where Inbound Webhooks are fire-and-forget (the caller immediately gets 202 Accepted and the flow runs in the background), an API Endpoint keeps the connection open and answers with whatever the flow decides.

When To Use API Endpoints

• The caller needs an answer in the same request — validation results, lookups, computed data, or a generated file.
• You want to publish an Action Flow as a service other systems can call.
• You need to reject bad requests up front: endpoint parameters are defined as JSON Schema and validated before the flow starts.

If the caller does not need a response, prefer an Inbound Webhook — it returns faster and is not limited by the synchronous timeout.

Create An API Endpoint

1. Open Gateways > API Endpoints and choose New API Endpoint.
2. Give the endpoint a name. The URL slug is suggested from the name and can be edited (lowercase letters, digits, and dashes).
3. Pick the HTTP method (POST by default).
4. Optionally define a request body schema and a query parameter schema as JSON Schema documents (see Schema Format). Requests that do not conform are rejected with 400 and validation details before a run starts. You can paste an example JSON request and generate a starting schema from it, then edit as needed. Optionally define a response body schema too: the JSON Schema that successful responses must match (see Responding To The Caller).
5. Pick an authentication method and, optionally, restrict callers by IP — the same options as Inbound Webhooks, plus named API keys (see below).
6. Save. The endpoint URL is ready immediately — use Copy to share it with the caller.

Then attach the Action Flow that handles the requests:

1. Create (or open) an Action Flow, set its trigger to API Request, and save the trigger.
2. In the trigger configuration, attach the endpoint from the API Endpoint panel — or pick the target Action Flow directly in the endpoint's settings.
3. Publish the Action Flow. Endpoint requests always run the published version.

Each endpoint runs exactly one Action Flow. An endpoint without an attached Action Flow rejects requests with 503 until one is attached. If you chose an authentication method, the generated secret is shown once after saving. Tenant admins manage endpoints; attaching an Action Flow needs the same access as editing the flow itself.

Schema Format

The request body, query and response body schema fields accept JSON Schema 2020-12 (https://json-schema.org/draft/2020-12/schema). A $schema line is optional: a schema without one is read as 2020-12. The schema editor autocompletes keywords, shows what each keyword means when you hover over it, and underlines keywords it does not recognise.

Describe each property so API callers and the Action Flow know what to send and what to expect:

Keyword	Purpose
description	What the value means. Shown in the API catalog and documentation.
default	The value callers may assume when the property is omitted. Documentation only: Studio does not fill it into the request, so the Action Flow applies the fallback itself (for example in a Code step).
examples	An array of sample values, for example ["123123"]. Shown in the API documentation.
title	A short display name for the value.
deprecated	Marks a value callers should stop sending or relying on.
readOnly, writeOnly	The value is only returned (never sent), or only sent (never returned).
enum, const, format, pattern, minimum, maxLength, ...	Standard validation constraints. format is documentation only and is not enforced.

{
  "type": "object",
  "required": ["invoiceNumber"],
  "properties": {
    "invoiceNumber": {
      "type": "string",
      "description": "Invoice number",
      "default": "-",
      "examples": ["123123"]
    },
    "dueDate": {
      "type": ["string", "null"],
      "format": "date",
      "description": "Due date, or null when not yet known"
    }
  },
  "additionalProperties": false
}

Keywords from other conventions are saved but ignored, so use the JSON Schema spelling instead:

• example (OpenAPI 3.0, a single value): use examples with an array.
• nullable: true (OpenAPI 3.0): use a type list such as "type": ["string", "null"].
• defaultValue: use default.

Generate from JSON example marks every field of the pasted example as required and records the example values in examples, so you only need to add descriptions and relax required. The API catalog publishes the schemas unchanged as an OpenAPI 3.1 document, whose schema objects are JSON Schema 2020-12, so these annotations appear in the generated API documentation.

Named API Keys

The API key authentication mode replaces the single per-endpoint secret with named keys managed in the API keys section of the API Endpoints page. Callers send their key in the X-Api-Key header.

• A tenant can have multiple keys — typically one per calling system, named after it (for example "ERP integration").
• Each key can be disabled, rotated, or deleted individually, can carry an optional expiry time, and can be scoped to specific endpoints (an unscoped key is valid on every endpoint using the API key mode).
• Requests are attributed to the key that authenticated them: the Action Flow sees inputs.triggerPayload.apiKey with the key's id and name, so a flow can tell its callers apart.
• Like endpoint secrets, the full key is shown once when created or rotated — store it right away. Only the key's prefix is shown afterwards.

Endpoints using the API key mode have no per-endpoint secret to rotate — rotate the individual keys instead.

The Request Inside The Flow

The incoming request is available to the flow as inputs.triggerPayload:

{
  "method": "POST",
  "path": "/endpoints/{tenantId}/{slug}",
  "query": { "source": "erp" },
  "headers": { "content-type": "application/json" },
  "body": { "invoiceNumber": "INV-1", "amount": 125.5 }
}

Authentication headers and the configured secret are stripped before the payload reaches the flow. Request bodies must be JSON (128 KB by default); GET and DELETE requests carry their input in query parameters instead.

Responding To The Caller

Use the Respond_To_Api_Request tool in an Agent or Tool Call step to compose the response: status code, headers, and a JSON, text, or binary (base64) body. The response is sent when the run finishes.

• If the tool is not used, the endpoint returns 200 OK with { "runId": "..." }.
• If the tool runs more than once, the last response wins.
• The tool only works in the run started by the API request itself. Follow-up Action Flows started with a Trigger Action step cannot respond to the original request — respond first, then hand heavy work to follow-up flows.

Every response carries X-Dooap-Run-Id and X-Dooap-Request-Id headers so a call can be correlated with its run.

Response Body Schema

When callers depend on a fixed response shape, declare a response body schema (JSON Schema) on the endpoint. It works as a contract in three places:

• Inside the run. When the flow calls Respond_To_Api_Request with a successful (2xx) JSON body that does not match the schema, the tool call fails and returns the violations together with the expected schema. Nothing has been sent to the caller yet, so an Agent step simply corrects the body and calls the tool again. Error responses (4xx/5xx) and binary bodies are not validated, so the flow can still return its own error payloads.
• In the flow's inputs. The schema is passed to the run as the apiResponseBodySchema input parameter. Mention it in the agent instructions ("compose the response according to apiResponseBodySchema") so the first attempt already conforms.
• In the API catalog. The schema is published as the 200 response of the operation, so API clients generated from the catalog know what to expect.

Like the request schemas, you can paste an example JSON response and generate a starting schema from it.

Timeouts And Long-Running Flows

Each endpoint has a timeout (default 60 seconds, maximum 220). When the run takes longer, the caller receives 202 Accepted with the run id and the run continues in the background. The same happens when the flow suspends into a Human Task — an API caller cannot wait for a person, so the response includes the task reference.

Keep synchronous endpoints fast: validate, respond, and defer slow work to follow-up flows via Trigger Action steps.

The API Catalog

The API catalog button on the API Endpoints page generates an OpenAPI 3.1 document covering the tenant's enabled endpoints with an attached Action Flow — the tenant's actual API surface. Each operation carries the endpoint's request body, query, and response body schemas, its authentication scheme, and the Action Flow it runs. Copy or download the document to import it into API clients, or share it with the teams calling your endpoints. For a human-readable version of the same document, see API Documentation below.

API Documentation

The API documentation button next to the API catalog opens a browsable reference of the same OpenAPI document in a new browser tab, rendered with Redoc. The page contains nothing but the documentation — no Studio menus or panels — and lives at /t/<tenant id>/gateways/api-endpoints/doc, so the link can be shared with the developers integrating against your endpoints. They see every callable operation with its URL, HTTP method, authentication requirement, request and query parameters, response schemas and generated example payloads, without reading raw JSON. Opening the link requires a Dooap Studio login with access to the tenant.

The documentation always reflects the current state of the tenant's endpoints: creating, enabling or re-attaching an endpoint, or changing its schemas, updates the reference on the next load. The Download link at the top of the page saves the underlying OpenAPI document for API clients and code generators. Like the catalog, only enabled endpoints with an attached Action Flow appear — the page tells you when none is callable yet.

Exporting Endpoints With An Action Flow

When you export an Action Flow that uses the API Request trigger, the endpoints attached to it are included: name, slug, method, request/query/response schemas, timeout, and authentication mode. Secrets, API keys, and IP allowlists are never exported. Importing the flow (or a Library template built from it) matches endpoints by slug: a new slug is created and attached to the new flow, while an existing endpoint with the same slug is reused and re-attached to the imported flow, so its public URL and IP allowlist stay the same. When the import defines the endpoint differently (schemas, timeout, method, authentication mode, ...), the import wizard lists the differences and lets you update the endpoint from the import or create a new endpoint with a numeric suffix instead. Endpoints with a secret-based authentication mode get a new secret, shown once, when they are created or switched to that mode.

Monitoring

Received requests appear in the Trigger Stream with their payloads, and every run shows up in the Action Flow's run history like any other run. Failed requests (authentication, schema validation) are rejected before a run starts and do not consume credits.

---