drio
Version 2
You're viewing archived v1 docs.View latest

API Overview

Archived overview of the drio v2 management API and draft/release model.

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

This archived docs set describes v2, the previous control-plane API.

If you need the older v1 contract for migration or historical reference, use the archived v1 docs.

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 release workflows

If you are primarily 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:

  • create blank apps or starter-backed apps
  • inspect app, draft, and release state
  • 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
  • publish releases 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.

The Core Model

The supported API is built around four concepts:

  • app: the stable container and top-level metadata
  • draft: the current mutable working state for that app
  • release: an immutable published snapshot
  • current-draft-backed authoring resources such as auth connections, integrations, tools, and widgets

Normal writes update the app's current draft. Publishing creates a release and rotates the app to a fresh successor draft.

Main Workflow

Today, the API is centered around this flow:

  1. discover auth
  2. authenticate
  3. create an app
  4. create auth connections and integrations
  5. create operations, tools, and widgets
  6. inspect the app and its draft
  7. publish a release

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

Base Routes

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

What The API Supports Today

Use these with a bearer access token.

  • GET /api/v2/me
  • GET /api/v2/auth-providers
  • GET /api/v2/integration-providers
  • GET /api/v2/apps
  • POST /api/v2/apps
  • GET /api/v2/apps/{app_id}
  • PATCH /api/v2/apps/{app_id}
  • GET /api/v2/apps/{app_id}/draft
  • GET /api/v2/apps/{app_id}/draft/changes
  • GET /api/v2/apps/{app_id}/releases
  • GET /api/v2/apps/{app_id}/releases/{release_id}
  • POST /api/v2/apps/{app_id}/releases
  • GET|POST /api/v2/apps/{app_id}/auth-connections
  • GET|PATCH|DELETE /api/v2/apps/{app_id}/auth-connections/{auth_connection_id}
  • GET|POST /api/v2/apps/{app_id}/integrations
  • GET|PATCH|DELETE /api/v2/apps/{app_id}/integrations/{integration_id}
  • GET|POST /api/v2/apps/{app_id}/integrations/{integration_id}/operations
  • GET|PATCH|DELETE /api/v2/apps/{app_id}/operations/{operation_id}
  • GET|POST /api/v2/apps/{app_id}/tools
  • GET|PATCH|DELETE /api/v2/apps/{app_id}/tools/{tool_id}
  • PUT /api/v2/apps/{app_id}/tools/{tool_id}/binding
  • PUT /api/v2/apps/{app_id}/tools/{tool_id}/chain
  • GET|POST /api/v2/apps/{app_id}/widgets
  • GET|PATCH|DELETE /api/v2/apps/{app_id}/widgets/{widget_id}
  • PUT /api/v2/apps/{app_id}/widgets/{widget_id}/actions

Auth Model

drio publishes the discovery entrypoints for the management API, but the OAuth authorization server is AuthKit.

In practice the boundary is:

  • start at drio discovery
  • register the client with AuthKit
  • authorize and exchange tokens with AuthKit
  • call drio's protected routes with the returned bearer token

OAuth-aware clients can usually discover the required endpoints automatically from /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

Typical Flow

Mermaid diagram source:
sequenceDiagram
  autonumber
  participant Client as API client
  participant Drio as drio API
  participant AuthKit as AuthKit

  Client->>Drio: Discover /.well-known metadata
  Client->>AuthKit: Register client via DCR
  Client->>AuthKit: Authorize with PKCE
  AuthKit-->>Client: Redirect back with authorization code
  Client->>AuthKit: Exchange code for tokens
  AuthKit-->>Client: access_token + refresh_token
  Client->>Drio: Call /api/v2/apps with Bearer token
  Drio-->>Client: Protected API response

What The Client Needs To Keep Stable

For the authorization code flow to work cleanly:

  • discover the authorization server from drio first
  • keep the returned client_id
  • send the same registered redirect_uri during authorize and token exchange
  • keep PKCE enabled for authorization code flow

Continue With