Custom integrations
Wrap a REST API as a custom tool
Most internal systems already speak REST. Dezifi turns them into first-class agent tools with typed actions, scoped auth and full tracing — no glue code.
What you'll learn
- How to model a REST API as a set of agent actions
- Which auth schemes Dezifi supports out of the box
- How parameters, request bodies and responses are typed
- How to scope, rate-limit and audit REST tool calls
How REST tools are structured
A REST tool in Dezifi is a named connection plus a set of actions. Each action maps to one endpoint with a typed input and output schema.
- 1
Connection
Base URL, auth configuration and global headers. One connection per environment — staging and prod stay separate. - 2
Action
Method (GET, POST, PUT, PATCH, DELETE), path template, parameter schema, response schema. Each action becomes a callable function the agent sees. - 3
Schemas
Provide an OpenAPI / Swagger spec to auto-generate actions, or define them manually in the builder. The schema drives parameter validation and the function signature presented to the LLM.
Authentication options
- API key — header or query parameter. Stored encrypted, never exposed to the agent.
- Bearer token — static token or refresh-rotated. Supports per-workspace and per-user tokens.
- Basic auth — username and password over HTTPS. Use sparingly; prefer API key or OAuth.
- OAuth 2.0 — authorization code flow with PKCE. Dezifi handles the redirect, token storage and refresh.
- Custom signed headers — HMAC-SHA256 over the request body, useful for partner APIs.
How to register a REST API
- 1
Open Integrations
Sidebar → Integrations → New → REST API. - 2
Set the connection
Name, base URL, auth scheme. If you have an OpenAPI spec, upload it now — Dezifi auto-creates actions and schemas. - 3
Define actions manually if no spec
Click Add Action. Give it a name like "createOrder". Set method, path template, parameters, optional request body, response schema. Add a one-sentence description — the LLM uses it to pick the right action. - 4
Test each action
Use the inline tester. Provide sample parameters, click Run. Dezifi shows the raw request, response and parsed output. Fix schema issues here, not in production. - 5
Attach to an agent
In the agent builder, add the REST tool. Pick which actions the agent can call. Add a rate-limit policy if the upstream API has quotas.
Scoping, rate limits and audit
Apply per-tool policies to cap calls per minute or per run, restrict actions by environment, or require approval on destructive endpoints (DELETE, certain POSTs). Every call is recorded in the trace with full request and response — credentials masked — so audit and debugging share one data path.
Frequently asked questions
- Do I need to write any code?
- No. If you have an OpenAPI spec, upload it and you're done. If not, define actions in the builder. Code is only needed if you require complex request signing — and even then, custom signed headers cover most cases.
- How are credentials stored?
- Encrypted at rest with workspace-scoped keys. The agent runtime injects them at call time; they never appear in prompts, traces or logs.
- Can different agents use different credentials for the same API?
- Yes. Register the API multiple times with different credentials, or use OAuth so each user authenticates individually. Per-user OAuth is the right answer for agents acting on behalf of an end user.
- What happens on a 429 or 5xx from the upstream?
- Dezifi applies exponential backoff with a configurable retry policy. After max retries, the tool call returns an error and the agent decides — usually it reports the failure and stops the workflow.