Build Integrations From API Specs

Use Integrations → API specs to turn selected operations from an external API into tools your Organization's agents can use. Switch to the Organization workspace first. Organization roles authorized to manage agents can manage these integrations.

This is a connection to another service. The platform's own developer API is documented separately.

Prepare and import a specification

Obtain the provider's OpenAPI 3 specification as JSON or YAML and the intended API base URL. Use a bundled specification: external $ref documents are not fetched. The confirmed base URL must use HTTPS and pass destination validation; a server address inside the specification does not silently authorize another destination.

Choose Add API spec, enter its name and confirmed base URL, then upload the specification. Review the draft operation list and any warnings.

Before the integration's first publication, you can change API base URL in the draft workbench. Save draft saves the URL and operation settings; Publish saves those edits before publishing. Changing the URL does not require uploading the specification again.

The supported subset covers path, query, and ordinary header parameters with JSON request and response bodies. Callbacks, binary or multipart payloads, cookie parameters, and authentication headers supplied as tool arguments are not supported. Unsupported operations cannot be published. Put authentication in the integration's credential settings instead.

Select tools and policies

For each useful operation, review its tool name, description, and access policy. Select only the operations the agent needs.

Tool names can contain ASCII letters, digits, and single underscores, must start and end with a letter or digit, and must be at most 56 characters long. Saving or publishing rejects names that need further normalization and suggests a replacement. Imported names meet these rules automatically; a short stable suffix distinguishes collisions.

Specifications can initialize these draft settings with operation-level extensions:

Extension	Value
x-dt-tool-name	Suggested tool name, normalized to the supported name format
x-dt-policy	read, autonomous, or approval
x-dt-redact	List of response redaction paths, such as ["/customer/ssn"]

For example, this bundled specification seeds a read tool and redacts the returned email address:

openapi: 3.0.3
info:
  title: Customer API
  version: '1.0'
paths:
  /customer:
    get:
      operationId: getCustomer
      x-dt-tool-name: lookup_customer
      x-dt-policy: read
      x-dt-redact:
        - /email
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  email:
                    type: string

Without a recognized policy, GET and HEAD default to read; other methods default to approval. Matching operations retain their previously published settings on reimport, taking precedence over these suggestions.

Policy	Behavior
Read	Allows the operation as a read tool; verify the provider's actual behavior
Autonomous write	Allows an authorized agent to execute the operation without a per-call approval card
Approval required	Holds the proposed call until a configured approver decides

Do not infer safety solely from an operation's name. Inspect the method, path, parameters, and provider behavior. Configure response redaction paths for sensitive fields that should not appear in tool results; use JSON Pointer paths such as /customer/ssn for the actual response shape.

The read policy does not restrict the operation's HTTP method. Both read and autonomous skip per-call approval; use approval when a call requires human review.

Save the draft, then Publish selected when the operation set and policies are ready. Uploading or saving a draft alone does not replace the published tools.

Connect credentials and agents

The integration supports no authentication, API keys in headers or query parameters, bearer tokens, basic authentication, OAuth authorization code, and OAuth client credentials. Use the mode supported by the provider and enter credentials through the protected controls.

Create an agent binding with the intended credential. Member-owned credentials require an explicit grant for that agent; the platform does not choose whichever member most recently signed in. Verify the identity and scope before binding.

Check the destination shown beside the connection controls before entering a key or connecting OAuth. Credentials are restricted to that API origin, including its scheme and port. If the destination changes while the form is open, refresh and review it before connecting again. A credential cannot be reassigned to another destination through an existing sharing grant.

To give access by default, open Authentication and agent access, select Assign to all current and future agents, choose an Organization credential when authentication is required, and click Save automatic access. This adds bindings for current agents without an assignment and for agents subsequently created in or moved into the Organization, including Teams. Evaluation and deleted agents are excluded. A draft's bindings become usable when its tools are published.

Existing bindings keep their credentials and approvers. Remove access on an individual agent creates an exception that automatic assignment preserves; Save agent access restores that agent explicitly. Changing the defaults applies to new assignments. Turning automatic access off leaves existing bindings in place.

Default write approvers must have Organization-wide agent management permission, which is checked again for each new assignment. Member-owned credentials remain available only through individual bindings and explicit grants. Changing authentication settings revokes existing credentials and turns automatic access off; reconnect credentials and configure access again. Revoking the default credential also turns automatic access off.

For approval-required operations, configure at least one approver authorized to manage that agent. Without a configured approver, the write fails rather than becoming autonomous. Begin with a read request against a known record and inspect the result, then test a narrowly scoped write using the selected policy.

Approve and reconcile writes

Publication and execution authority are separate. An administrator must review the exact operation contract and connection, then grant the current capability. Imported descriptions, HTTP methods and x-dt-policy do not establish a safe classification. Changed contracts or credentials invalidate affected grants. Configure finite destination/Organization disclosure budgets; a host approval alone does not permit context processing or provider-mediated sends.

With automatic mixed-capability review enabled, external operations need complete independent action review unless a narrow processing grant covers a reviewed fixed service operation. GET requests can disclose data too. Selected recipients, arbitrary destinations and opaque effects retain review obligations. Review shows the full prepared request and configured credential identity, with injected authentication secrets masked. Oversized, redacted or unavailable material cannot be approved. Renew expired credentials before preparing review. Missing authority or exhausted budgets blocks dispatch even after a human approves the action.

Review the exact operation and arguments in the pending request. Approval is tied to that request's revision, credential, and execution configuration. It is not blanket approval for later calls. Expired or invalidated requests must be proposed again. Calls whose arguments do not match the operation's input schema, such as a value outside an allowed list, are returned to the agent as validation errors and never reach the approval queue.

After a timeout or an uncertain outcome, inspect the provider before requesting another write. The original call may have succeeded even if its response did not arrive. See Approvals And Requests.

Update or disconnect

Import the replacement specification as a new draft, inspect changes to operations and policies, then publish it. Review changed operations and agent bindings after publication. Changing connection or authentication context can invalidate bindings and pending approvals; reconnect and grant access deliberately when requested.

Changing the API origin or authentication settings permanently revokes all existing credentials, removes agent access, turns automatic access off and invalidates waiting approvals and OAuth sessions. Enter fresh credentials or reconnect OAuth, share the new member credential with the intended agents, and explicitly restore agent and automatic access. Returning to the previous URL does not restore the old credentials. A same-origin API path change retains credentials and agent access but invalidates waiting calls. A call already admitted may finish at its original destination; check the provider before repeating an uncertain write.

Re-import preserves valid curated names and policies. If an older published name contains repeated underscores or exceeds the name limit, the new draft repairs it and shows the old and new names in its warnings. Review those warnings before publishing. The existing published revision continues using its stored names until publication; upgrading the workers allows those existing names to execute without re-publishing. Re-import also refreshes argument schemas that older imports may have omitted for these names.

Disable the integration to stop exposing its tools while retaining configuration. Removing an agent binding removes that agent's tool access. Neither action reverses writes already completed at the provider.