ReferenceHTTP API

HTTP API

This page documents the HTTP surface exposed by gestaltd.

Authentication Model

Authenticated routes accept:

  • the session_token cookie
  • or Authorization: Bearer <token>

For proxy routes, Gestalt also understands:

  • Proxy-Authorization: Bearer <token>

Valid bearer tokens are:

  • platform session tokens
  • Gestalt API tokens (gst_api_...)

Unauthenticated Routes

MethodPathPurpose
GET/healthBasic liveness check.
GET/readyReadiness check. Returns 503 until providers and datastore are ready.
GET/api/v1/auth/infoReturns platform auth metadata.
POST/api/v1/auth/loginStarts platform login.
GET/api/v1/auth/login/callbackCompletes platform login.
POST/api/v1/auth/logoutClears the current platform session.
GET/api/v1/auth/callbackCompletes integration OAuth.
POST/api/v1/auth/pending-connectionRender or finalize a multi-candidate connection choice using a pending connection token.

Authenticated User Routes

Integrations

MethodPathPurpose
GET/api/v1/integrationsList integrations, connection state, auth types, instances, icons, and connection parameter hints.
DELETE/api/v1/integrations/{name}Disconnect an integration. Use ?instance=... when more than one connection exists.
GET/api/v1/integrations/{name}/operationsList operations for one integration.
GET or POST/api/v1/{integration}/{operation}Invoke an integration operation.

Integration Connection Flows

MethodPathPurpose
POST/api/v1/auth/start-oauthStart an integration OAuth flow.
POST/api/v1/auth/connect-manualSubmit manual integration credentials.

API Tokens

MethodPathPurpose
POST/api/v1/tokensCreate an API token. Plaintext is returned once.
GET/api/v1/tokensList API tokens for the current user.
DELETE/api/v1/tokens/{id}Revoke an API token.
DELETE/api/v1/tokensRevoke all API tokens for the current user.

Binding Discovery

MethodPathPurpose
GET/api/v1/bindingsList configured bindings.

Dynamic Binding Routes

Bindings may add routes under:

/api/v1/bindings/{binding-name}/...

The exact paths and auth behavior depend on the binding type and its config.

MCP

If any integration is MCP-enabled, Gestalt also mounts:

MethodPathPurpose
GET or POST/mcpModel Context Protocol endpoint.

/mcp is authenticated with the same session or bearer-token middleware as the rest of the authenticated API.

Invocation Semantics

When you call:

/api/v1/{integration}/{operation}

Gestalt:

  1. authenticates the caller
  2. resolves the target provider and operation
  3. resolves credentials based on the connection’s mode
  4. auto-selects an instance when there is exactly one
  5. fails with an ambiguity error when there are multiple instances and none is specified
  6. refreshes OAuth tokens when needed
  7. executes the provider operation

Parameter Conventions

  • GET invocations read parameters from the query string
  • POST invocations read parameters from a JSON body
  • _instance can be supplied when an integration has more than one stored connection

Example

curl http://localhost:8080/api/v1/httpbin/get_headers
Plugin ManifestsCLI