Integrations

Endpoints

Method	Path	Purpose
`POST`	`/integrations`	Create integration
`GET`	`/integrations`	List integrations
`GET`	`/integrations/:id`	Get integration
`PATCH`	`/integrations/:id`	Update integration
`DELETE`	`/integrations/:id`	Archive integration
`POST`	`/integrations/:id/validate`	Validate connectivity
`GET`	`/integrations/:id/oauth`	Get OAuth config
`PUT`	`/integrations/:id/oauth`	Replace OAuth config
`DELETE`	`/integrations/:id/oauth`	Remove OAuth config
`POST`	`/integrations/:id/connection`	Add user token
`GET`	`/integrations/:id/connection`	Get connection status
`DELETE`	`/integrations/:id/connection`	Revoke connection

id path params are UUIDs.

Create integration

curl -X POST https://api.kontext.dev/api/v1/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub",
    "url": "https://mcp.github.com/sse",
    "category": "gateway_remote_mcp",
    "authMode": "oauth",
    "oauth": {
      "provider": "github",
      "scopes": ["repo", "read:user"]
    }
  }'

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Display name
`url`	`string`	Yes	MCP endpoint URL of the integration
`category`	`string`	No	`"gateway_remote_mcp"` (default) or `"internal_mcp_credentials"`
`authMode`	`string`	No	`"oauth"`, `"user_token"`, `"server_token"`, or `"none"` (default)
`oauth`	`object`	No	OAuth configuration. Fields: `provider?`, `issuer?`, `scopes?`
`capabilities`	`object`	No	Declared capabilities: `{ tools?, resources?, prompts? }`
`credentialSchema`	`object`	No	Schema for user-provided credentials
`serverToken`	`string`	Conditional	Required when `authMode` is `"server_token"`

Auth modes

Mode	Description
`oauth`	Users authenticate via OAuth. Kontext manages the token lifecycle.
`user_token`	Users provide a personal access token or API key manually.
`server_token`	A single shared token configured at the organization level.
`none`	No authentication required.

List integrations

curl "https://api.kontext.dev/api/v1/integrations?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Returns a paginated list of all integrations in the organization. Query parameters: limit, cursor, and optional name substring filter.

Get integration

curl https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer $TOKEN"

Response fields

Response shape: { "integration": { ... } }

Field	Type	Description
`id`	`string`	Integration ID
`name`	`string`	Display name
`url`	`string`	Base URL
`category`	`string`	`"gateway_remote_mcp"` or `"internal_mcp_credentials"`
`authMode`	`string`	Authentication mode
`oauth`	`object?`	OAuth configuration (if applicable)
`capabilities`	`object?`	Declared capabilities
`credentialSchema`	`object?`	Schema for user credentials
`serverTokenConfigured`	`boolean`	Whether a server token is set
`validationStatus`	`string`	Last validation result (`"pending"`, `"valid"`, `"invalid"`)
`validationMessage`	`string?`	Human-readable validation message
`lastValidatedAt`	`string?`	ISO 8601 timestamp of last validation
`userConnection`	`object?`	Current user’s connection status
`createdAt`	`string`	ISO 8601 timestamp
`updatedAt`	`string`	ISO 8601 timestamp

Update integration

curl -X PATCH https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "GitHub Enterprise" }'

Partial update. Send only the fields you want to change.

Archive integration

curl -X DELETE https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer $TOKEN"

Archives the integration. It will no longer be available for new connections, but existing data is preserved.

Validate connectivity

curl -X POST https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/validate \
  -H "Authorization: Bearer $TOKEN"

Tests whether Kontext can reach the integration’s URL and authenticate. Updates the validationStatus, validationMessage, and lastValidatedAt fields on the integration.

Get OAuth config

curl https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN"

Returns the OAuth configuration for the integration. Only available when authMode is "oauth".

Response fields

Response shape: { "oauth": { ... } }

Field	Type	Description
`provider`	`string`	OAuth provider identifier
`issuer`	`string`	Token issuer URL
`scopes`	`string[]`	Requested OAuth scopes

Replace OAuth config

curl -X PUT https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "scopes": ["repo"]
  }'

Full replacement — you must include all OAuth fields. Existing user connections may need to re-authenticate.

Remove OAuth config

curl -X DELETE https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN"

Removes the OAuth configuration. You need to set a different authMode before removing OAuth, or the integration will have no auth.

Add user token

curl -X POST https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "token": "ghp_xxxxxxxxxxxx" }'

Stores a personal access token or API key for the current user on this integration. Used when authMode is "user_token".

Get connection status

curl https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN"

Returns the current user’s connection status for this integration.

Response fields

Response shape: { "connection": { ... } }

Field	Type	Description
`connected`	`boolean`	Whether a credential is stored
`status`	`string`	`"connected"` or `"disconnected"`
`expiresAt`	`string?`	ISO 8601 expiry timestamp
`displayName`	`string?`	Display name from the provider

Revoke connection

curl -X DELETE https://api.kontext.dev/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN"

Removes the current user’s stored credential for this integration. For OAuth connections, this also revokes the token with the upstream provider when possible.

The OAuth config, connection, and revoke endpoints are REST-only. Use the Management SDK for the core CRUD operations (create, list, get, update, archive, validate).

SDK Reference

REST API

Endpoints

Create integration

Request body

Categories

Auth modes

List integrations

Get integration

Response fields

Update integration

Archive integration

Validate connectivity

Get OAuth config

Response fields

Replace OAuth config

Remove OAuth config

Add user token

Get connection status

Response fields

Revoke connection

SDK Reference

REST API

​Endpoints

​Create integration

​Request body

​Categories

​Auth modes

​List integrations

​Get integration

​Response fields

​Update integration

​Archive integration

​Validate connectivity

​Get OAuth config

​Response fields

​Replace OAuth config

​Remove OAuth config

​Add user token

​Get connection status

​Response fields

​Revoke connection

Endpoints

Create integration

Request body

Categories

Auth modes

List integrations

Get integration

Response fields

Update integration

Archive integration

Validate connectivity

Get OAuth config

Response fields

Replace OAuth config

Remove OAuth config

Add user token

Get connection status

Response fields

Revoke connection