GEKI
GEKI API
GEKI API

connections

How bots reach other services. /v1/mcp-connectors: remote MCP servers of the org. /v1/oauth-apps: how to sign in at a provider. /v1/connected-accounts: the sign-ins of people and of the org. Beta.

List connected accounts

GET
https://api.geki.ai
/v1/connected-accounts
Bearer

The caller's own accounts. With all=true every account of the org, personal and shared, for people with connector:write. No response holds a token.

List connected accounts › query Parameters

limit
​integer · min: 1 · max: 100
Default: 20
after
​
before
​
order
​string · enum
Enum values:
asc
desc
Default: desc
all
​boolean

Every account of the org. Needs connector:write.

Every account of the org. Needs connector:write.

Default: false

List connected accounts › Responses

Successful Response

Page_ConnectedAccount_
​ConnectedAccount[] · required
​
has_more
​boolean
Default: false
​
object
​string · const
Const value: list
Default: list

Disconnect an account

DELETE
https://api.geki.ai
/v1/connected-accounts/{account_id}
Bearer

Deletes the account and revokes the token at the provider when it has a revocation URL. A person disconnects their own. connector:write disconnects any account.

Disconnect an account › path Parameters

account_id
​string · uuid · required

Disconnect an account › Responses

Successful Response

Deleted
id
​string · required
object
​string · required
deleted
​boolean · const
Const value:
Default: true

List MCP connectors

GET
https://api.geki.ai
/v1/mcp-connectors
Bearer

List MCP connectors › query Parameters

limit
​integer · min: 1 · max: 100
Default: 20
after
​
before
​
order
​string · enum
Enum values:
asc
desc
Default: desc

List MCP connectors › Responses

Successful Response

Page_McpConnector_
​McpConnector[] · required
​
has_more
​boolean
Default: false
​
object
​string · const
Const value: list
Default: list

Create an MCP connector

POST
https://api.geki.ai
/v1/mcp-connectors
Bearer

Needs connector:write. Bots reference the MCP connector by id and choose allowed tools and approvals per bot. The auth mode applies to every bot, the Personal bot too. none sends no credential. shared needs a credential_id. per_person uses the account of the person who writes: a token they paste (PUT /v1/mcp-connectors/{id}/token), or, with oauth_app_id and pass_through, their sign-in at that OAuth app.

Create an MCP connector › Request Body

McpConnectorCreate
label
​string · required
url
​string · required
auth_mode
​string · enum
Enum values:
none
shared
per_person
Default: none
​
enabled
​boolean
Default: true
​
​
​
operator
​string · maxLength: 255
Default:
pass_through
​boolean
Default: false

Create an MCP connector › Responses

Successful Response

McpConnector
auth_mode
​string · enum · required
Enum values:
none
shared
per_person
created_at
​string · required
​required

shared: a bearer token or a sign-in in an org vault.

enabled
​boolean · required

Off stops all use from the next turn.

​required
id
​string · required
label
​string · required

The server label of the MCP tool. Unique in the org.

​required

The sign-in the MCP connector owns, set up from the MCP authorization flow.

​required

per_person with pass_through: the OAuth app whose token is sent.

operator
​string · required

Free text: who runs the server and where.

pass_through
​boolean · required

Send a person's token of oauth_app_id to this server. Off by default.

updated_at
​string · required
url
​string · required
object
​string · const
Const value: mcp_connector
Default: mcp_connector

Probe an MCP server for OAuth

POST
https://api.geki.ai
/v1/mcp-connectors/probe
Bearer

Needs connector:write or agent:write. Asks the server how to sign in (protected resource metadata, then the authorization server) and says whether GEKI can be a client there. Nothing is registered or stored.

Probe an MCP server for OAuth › Request Body

McpProbe
url
​string · required

Probe an MCP server for OAuth › Responses

Successful Response

McpProbeResult
​required

How GEKI can be a client there. null with oauth: the admin enters a client.

​required
oauth
​boolean · required

The server follows the MCP authorization flow.

scopes
​string[] · required

Read an MCP connector

GET
https://api.geki.ai
/v1/mcp-connectors/{connector_id}
Bearer

Read an MCP connector › path Parameters

connector_id
​string · uuid · required

Read an MCP connector › Responses

Successful Response

McpConnector
auth_mode
​string · enum · required
Enum values:
none
shared
per_person
created_at
​string · required
​required

shared: a bearer token or a sign-in in an org vault.

enabled
​boolean · required

Off stops all use from the next turn.

​required
id
​string · required
label
​string · required

The server label of the MCP tool. Unique in the org.

​required

The sign-in the MCP connector owns, set up from the MCP authorization flow.

​required

per_person with pass_through: the OAuth app whose token is sent.

operator
​string · required

Free text: who runs the server and where.

pass_through
​boolean · required

Send a person's token of oauth_app_id to this server. Off by default.

updated_at
​string · required
url
​string · required
object
​string · const
Const value: mcp_connector
Default: mcp_connector

Update an MCP connector

POST
https://api.geki.ai
/v1/mcp-connectors/{connector_id}
Bearer

Needs connector:write. Only the fields sent change. A mode keeps only the fields it uses. The URL and the label apply at the next turn.

Update an MCP connector › path Parameters

connector_id
​string · uuid · required

Update an MCP connector › Request Body

McpConnectorUpdate
​
​
​
​
​
​
​
​
​
​

Update an MCP connector › Responses

Successful Response

McpConnector
auth_mode
​string · enum · required
Enum values:
none
shared
per_person
created_at
​string · required
​required

shared: a bearer token or a sign-in in an org vault.

enabled
​boolean · required

Off stops all use from the next turn.

​required
id
​string · required
label
​string · required

The server label of the MCP tool. Unique in the org.

​required

The sign-in the MCP connector owns, set up from the MCP authorization flow.

​required

per_person with pass_through: the OAuth app whose token is sent.

operator
​string · required

Free text: who runs the server and where.

pass_through
​boolean · required

Send a person's token of oauth_app_id to this server. Off by default.

updated_at
​string · required
url
​string · required
object
​string · const
Const value: mcp_connector
Default: mcp_connector

Delete an MCP connector

DELETE
https://api.geki.ai
/v1/mcp-connectors/{connector_id}
Bearer

Needs connector:write. Deletes the pasted tokens of the MCP connector. 409 mcp_connector_in_use while a bot draft or live bot uses it.

Delete an MCP connector › path Parameters

connector_id
​string · uuid · required

Delete an MCP connector › Responses

Successful Response

Deleted
id
​string · required
object
​string · required
deleted
​boolean · const
Const value:
Default: true

Start a sign-in at the MCP server

POST
https://api.geki.ai
/v1/mcp-connectors/{connector_id}/connect
Bearer

For an MCP connector with an oauth setup. Returns the authorize URL; see POST /v1/oauth-apps/{id}/connect. A per_person MCP connector signs in the caller. A shared MCP connector needs vault_id and connector:write: the account lands in that org vault, and the MCP connector uses it once its credential_id names it.

Start a sign-in at the MCP server › path Parameters

connector_id
​string · uuid · required

Start a sign-in at the MCP server › Request Body

OAuthConnectRequest
return_url
​string · required

Where the callback sends the browser afterwards.

​

Sent to the provider, usually the person's email. A silent sign-in needs it.

​

Sent to the provider. none signs in without a screen. admin_consent is for Microsoft: an admin consents for the whole tenant.

​

An org vault. Connects one shared account there. Needs connector:write.

Start a sign-in at the MCP server › Responses

Successful Response

OAuthAuthorizeUrl
authorize_url
​string · required

Save a pasted token

PUT
https://api.geki.ai
/v1/mcp-connectors/{connector_id}/token
Bearer

For a per_person MCP connector without an OAuth app. Saves the caller's token as a connected account. Saving again replaces it. No route returns a token. DELETE /v1/connected-accounts/{id} removes it.

Save a pasted token › path Parameters

connector_id
​string · uuid · required

Save a pasted token › Request Body

McpTokenWrite
token
​string · minLength: 1 · maxLength: 8192 · required

Save a pasted token › Responses

Successful Response

No data returned

List the tools of an MCP server

POST
https://api.geki.ai
/v1/mcp-connectors/{connector_id}/tools
Bearer

Needs agent:write. Asks the MCP server live for its tools (tools/list, all pages up to a cap), which is why this is a POST. It uses the credential a turn of the caller would use: none, the shared one, or the caller's own account for per_person (403 person_required for a service account key). 400 needs_sign_in, needs_token, needs_credential, or turned_off when the MCP connector cannot be used. 502 when the server cannot be reached or refuses. Nothing is stored.

List the tools of an MCP server › path Parameters

connector_id
​string · uuid · required

List the tools of an MCP server › Responses

Successful Response

Page_McpConnectorTool_
​McpConnectorTool[] · required
​
has_more
​boolean
Default: false
​
object
​string · const
Const value: list
Default: list

List OAuth apps

GET
https://api.geki.ai
/v1/oauth-apps
Bearer

List OAuth apps › query Parameters

limit
​integer · min: 1 · max: 100
Default: 20
after
​
before
​
order
​string · enum
Enum values:
asc
desc
Default: desc

List OAuth apps › Responses

Successful Response

Page_OAuthApp_
​OAuthApp[] · required
​
has_more
​boolean
Default: false
​
object
​string · const
Const value: list
Default: list

Create an OAuth app

POST
https://api.geki.ai
/v1/oauth-apps
Bearer

Needs connector:write. Give the URLs, or an issuer and the server metadata fills them. The client secret is never returned.

Create an OAuth app › Request Body

OAuthAppCreate
client_id
​string · minLength: 1 · maxLength: 2000 · required
name
​string · minLength: 1 · maxLength: 80 · required
​object · maxProps: 20
​
client_auth
​string · enum
Enum values:
client_secret_post
client_secret_basic
Default: client_secret_post
​
enabled
​boolean
Default: true
grant_type
​string · enum
Enum values:
authorization_code
client_credentials
Default: authorization_code
​
​
​
scope_separator
​string · enum
Enum values:
,
Default:
scopes
​string[] · maxItems: 100
​
​

Create an OAuth app › Responses

Successful Response

OAuthApp
​object · required
​required
client_auth
​string · enum · required
Enum values:
client_secret_post
client_secret_basic
client_id
​string · required
created_at
​string · required
enabled
​boolean · required

Off stops all use of the app from the next turn.

grant_type
​string · enum · required
Enum values:
authorization_code
client_credentials
has_client_secret
​boolean · required

The client secret is write-only.

​required
id
​string · required
​required
name
​string · required
​required
scope_separator
​string · required
scopes
​string[] · required
token_url
​string · required
updated_at
​string · required
​required
object
​string · const
Const value: oauth_app
Default: oauth_app

Read an OAuth app

GET
https://api.geki.ai
/v1/oauth-apps/{app_id}
Bearer

Read an OAuth app › path Parameters

app_id
​string · uuid · required

Read an OAuth app › Responses

Successful Response

OAuthApp
​object · required
​required
client_auth
​string · enum · required
Enum values:
client_secret_post
client_secret_basic
client_id
​string · required
created_at
​string · required
enabled
​boolean · required

Off stops all use of the app from the next turn.

grant_type
​string · enum · required
Enum values:
authorization_code
client_credentials
has_client_secret
​boolean · required

The client secret is write-only.

​required
id
​string · required
​required
name
​string · required
​required
scope_separator
​string · required
scopes
​string[] · required
token_url
​string · required
updated_at
​string · required
​required
object
​string · const
Const value: oauth_app
Default: oauth_app

Update an OAuth app

POST
https://api.geki.ai
/v1/oauth-apps/{app_id}
Bearer

Needs connector:write. Only the fields sent change. A new client ID or token URL sets every account of the app to needs_sign_in.

Update an OAuth app › path Parameters

app_id
​string · uuid · required

Update an OAuth app › Request Body

OAuthAppUpdate
​
​
​
​
​
​
​
​
​
​
​
​
​
​

Update an OAuth app › Responses

Successful Response

OAuthApp
​object · required
​required
client_auth
​string · enum · required
Enum values:
client_secret_post
client_secret_basic
client_id
​string · required
created_at
​string · required
enabled
​boolean · required

Off stops all use of the app from the next turn.

grant_type
​string · enum · required
Enum values:
authorization_code
client_credentials
has_client_secret
​boolean · required

The client secret is write-only.

​required
id
​string · required
​required
name
​string · required
​required
scope_separator
​string · required
scopes
​string[] · required
token_url
​string · required
updated_at
​string · required
​required
object
​string · const
Const value: oauth_app
Default: oauth_app

Delete an OAuth app

DELETE
https://api.geki.ai
/v1/oauth-apps/{app_id}
Bearer

Needs connector:write. Deletes every account of the app. Tokens are not revoked. 409 oauth_app_in_use while an MCP connector sends its tokens or a bot draft or live bot maps it to a skill credential.

Delete an OAuth app › path Parameters

app_id
​string · uuid · required

Delete an OAuth app › Responses

Successful Response

Deleted
id
​string · required
object
​string · required
deleted
​boolean · const
Const value:
Default: true

Request a token into a vault

POST
https://api.geki.ai
/v1/oauth-apps/{app_id}/client-credentials
Bearer

Needs connector:write. For apps with grant_type client_credentials. Requests a token now and stores it in the org vault. The response is the connected account and holds no token. GEKI requests a new token when it expires.

Request a token into a vault › path Parameters

app_id
​string · uuid · required

Request a token into a vault › Request Body

OAuthClientCredentialsRequest
vault_id
​string · uuid · required

The org vault that holds the token.

Request a token into a vault › Responses

Successful Response

ConnectedAccount
created_at
​string · required
​required
id
​string · required
label
​string · required

The account name from the provider. Empty when unknown.

provider_id
​string · required

The OAuth app, the MCP connector, or the sign-in of a connector feature.

provider_kind
​string · enum · required

connector is Microsoft 365 on a Microsoft connector.

Enum values:
oauth_app
mcp_connector
connector
provider_name
​string · required
status
​string · enum · required
Enum values:
connected
needs_sign_in
​required

The person. null for a shared account.

updated_at
​string · required
​required

The org vault of a shared account.

object
​string · const
Const value: connected_account
Default: connected_account

Start a sign-in at the provider

POST
https://api.geki.ai
/v1/oauth-apps/{app_id}/connect
Bearer

Returns the authorize URL with PKCE and a signed state. Send the browser there. The callback /v1/oauth/callback stores the account and redirects to return_url. Without vault_id the account is the caller's own.

Start a sign-in at the provider › path Parameters

app_id
​string · uuid · required

Start a sign-in at the provider › Request Body

OAuthConnectRequest
return_url
​string · required

Where the callback sends the browser afterwards.

​

Sent to the provider, usually the person's email. A silent sign-in needs it.

​

Sent to the provider. none signs in without a screen. admin_consent is for Microsoft: an admin consents for the whole tenant.

​

An org vault. Connects one shared account there. Needs connector:write.

Start a sign-in at the provider › Responses

Successful Response

OAuthAuthorizeUrl
authorize_url
​string · required
knowledgerouting