# Integration docs

> The catalog of services the workspace can use and the reference for every operation: the same docs the agents read before they write a call.

Source: https://docs.generalinput.com/api/integrations



Two routers, one scope. `/v1/integrations` walks the catalog service by service; `/v1/operations` searches across every service at once and resolves a bare operation id. Both are read-only and free.

<Access scope="docs:read" />

## The shape of the catalog [#the-shape-of-the-catalog]

An **integration** is a service (`slack`, `stripe`, `search-internet`) with a credential type:

| `credentialType` | Meaning                                                                          |
| ---------------- | -------------------------------------------------------------------------------- |
| `oauth2`         | Connect through OAuth. The vault refreshes the access token.                     |
| `apiKey`         | Connect by pasting a key or token.                                               |
| `platform`       | A hosted General Input service. Nothing to connect; call it with `platform:use`. |
| `noAuth`         | A public API that needs no credential.                                           |

An **operation** is one documented call on a service ("Send a Message" on `slack`). Its `documentation` is markdown holding the HTTP method and path, params, response shape, an example, and the env var names a credential of that service injects into `geni exec bash` and agent runs.

## The discovery loop [#the-discovery-loop]

1. [Search operations](/api/integrations/search-operations) with a capability ("send slack message") to find the service and operation.
2. [Get the operation](/api/integrations/get-operation) to read its reference.
3. Find a credential for the service in the [vault](/api/vault), then call the third-party API yourself with a token from [issue a token](/api/vault/issue-token).

| Endpoint                                                                            | What it returns                         |
| ----------------------------------------------------------------------------------- | --------------------------------------- |
| [`GET /v1/integrations`](/api/integrations/list)                                    | Every integration the workspace can use |
| [`GET /v1/integrations/:service`](/api/integrations/get)                            | One integration's setup metadata        |
| [`GET /v1/integrations/:service/operations`](/api/integrations/list-operations)     | One service's operations                |
| [`GET /v1/integrations/:service/operations/:opId`](/api/integrations/get-operation) | One operation's full reference          |
| [`GET /v1/operations?q=`](/api/integrations/search-operations)                      | Cross-service operation search          |
| [`GET /v1/operations/:opId`](/api/integrations/get-operation-by-id)                 | One operation by bare id                |