API Overview - drio Docs

Understand what the drio management API covers and where it fits in the platform.

The drio API is a management API. It lets engineering teams automate the same core workflow they could otherwise perform in the dashboard: choose a template, create an app, wire up integrations, tools, and widgets, then deploy.

Who This Page Is For

developers integrating drio into internal workflows
technical reviewers evaluating the external API surface
teams that want to automate app creation and publishing

If you are a GTM or marketing operator building in the UI, you can usually skip this section and continue with the product-facing docs instead.

What The API Is For

Use the API to:

browse templates programmatically
create apps from templates
inspect app state and authoring config
create and update auth connections
create and update integrations and operations
create and update tools, bindings, and tool chains
create and update widgets and widget actions
update app metadata and branding
deploy apps from your own tooling

What The API Is Not For

The management API is separate from the deployed MCP endpoint used by end users inside ChatGPT, Claude, Cursor, or other AI clients.

Use:

the management API for app lifecycle automation
the MCP endpoint for runtime usage by AI clients

See Connect to AI clients for the runtime side.

Main Workflow

Today, the API is centered around this flow:

discover auth
authenticate
list templates
inspect a template
create an app from a template
create auth connections and integrations
create operations, tools, and widgets
inspect the app and its config
deploy the app

If you want the shortest working example, start with API quickstart.

Base Routes

resource API: /api/v1
OpenAPI document: /api/openapi.json
OAuth discovery:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource

What The API Supports Today

Public routes

Use these before authentication or when you only need template discovery.

GET /api/v1/templates
GET /api/v1/templates/{templateId}

Authenticated routes

Use these with a bearer access token.

GET /api/v1/me
GET /api/v1/apps
POST /api/v1/apps
GET /api/v1/apps/{appId}
PATCH /api/v1/apps/{appId}
GET /api/v1/apps/{appId}/config
POST /api/v1/apps/{appId}/deploy
GET|POST /api/v1/apps/{appId}/auth
GET|PATCH|DELETE /api/v1/apps/{appId}/auth/{authId}
GET|POST /api/v1/apps/{appId}/integrations
GET|PATCH|DELETE /api/v1/apps/{appId}/integrations/{integrationId}
GET|POST /api/v1/apps/{appId}/integrations/{integrationId}/operations
GET|PATCH|DELETE /api/v1/apps/{appId}/operations/{operationId}
GET|POST /api/v1/apps/{appId}/tools
GET|PATCH|DELETE /api/v1/apps/{appId}/tools/{toolId}
PUT /api/v1/apps/{appId}/tools/{toolId}/binding
PUT /api/v1/apps/{appId}/tools/{toolId}/chain
GET|POST /api/v1/apps/{appId}/widgets
GET|PATCH|DELETE /api/v1/apps/{appId}/widgets/{widgetId}
PUT /api/v1/apps/{appId}/widgets/{widgetId}/actions

Auth Model

drio exposes a standard OAuth 2.0 surface with discovery, dynamic client registration, authorization, token exchange, and refresh support. OAuth-aware clients can usually discover the required endpoints automatically.

Your client integrates with drio, not directly with WorkOS. drio owns the OAuth endpoints, validates the registered client_id and redirect_uri, handles the callback hop, and then exchanges the upstream code before returning tokens to the client.

Typical Flow

Mermaid diagram source:

sequenceDiagram
  autonumber
  participant Client as API client
  participant Drio as drio API
  participant WorkOS as WorkOS

  Client->>Drio: Discover /.well-known metadata
  Client->>Drio: Register at /api/v1/auth/register
  Client->>Drio: Start /api/v1/auth/authorize with client_id + redirect_uri
  Drio->>WorkOS: Redirect for sign-in
  WorkOS-->>Drio: Upstream authorization code callback
  Drio-->>Client: Redirect back with Drio auth code
  Client->>Drio: Exchange code at /api/v1/auth/token
  Drio-->>Client: access_token + refresh_token
  Client->>Drio: Call /api/v1/apps with Bearer token
  Drio-->>Client: Protected API response

What The Client Needs To Keep Stable

For the authorization code flow to work cleanly:

register the client first
keep the returned client_id
send the same registered redirect_uri during authorize and token exchange
treat /api/v1/auth/callback as a drio-owned bridge route, not a route your client calls directly