Connect a Custom API

Use a custom API connection when Type does not yet have a packaged connector for the service AI needs. Type stores the credential securely, then lets AI verify and finish the connection during its first managed use.

Before you start

Collect the details you already have:

• A name for the connection.
• An API key or OAuth client credentials.
• The API’s HTTPS base URL. A plain custom API requires this; a documentation URL is optional.
• Optional API notes or .md / .txt reference files.

Do not paste API keys into Space instructions, skills, thread messages, or CLI arguments. Use the connection form or the CLI’s credential pipe so Type can store and inject them safely.

Connect a plain custom API

1. Open Settings, then Connections.
2. Select Custom API.
3. Enter a clear name, such as Warehouse API or Billing API.
4. Add the HTTPS base URL and, optionally, a documentation URL.
5. Choose API key or OAuth under Auth method. Enter the API key, or the OAuth client ID, client secret, and token URL.
6. Optionally upload API reference files or enter notes in API description under Documentation (optional).
7. Choose whether the connection is available to your organization or only to you.
8. Save the connection.

Saving stores the credentials and supplied notes or files without testing the connection or checking documentation URL reachability. AI verifies and completes the API request setup when it first uses the connection.

Connect from a local agent or terminal

The Type CLI lets a local agent prepare the configuration. The default setup opens a Type form for the credential:

type-cli integrations connect custom \
  --scope personal \
  --config '{"name":"Warehouse API","baseUrl":"https://api.example.com","authScheme":"bearer","validationRequest":{"path":"/v1/me"}}' \
  --json --no-input

The draft contains only nonsecret details. It requires a name and HTTPS base URL, and can include API documentation and connection settings. Choose personal for your own credential or organization for a shared credential. For browser setup, enter the secret in the Type form, then press Save.

For terminal setup, use --terminal --secret-stdin --yes and pipe the credential from a password manager. The CLI reads it from the pipe; never put it in --config, a command argument, shell history, or an agent conversation. For a connection with no authentication, omit --secret-stdin. Terminal setup returns a verifyCommand directly. Browser setup returns a waitCommand for the exact attempt; after you save, that command returns a verifyCommand:

type-cli integrations wait <attempt-id> --json --no-input
type-cli integrations verify <attempt-id> --json --no-input

Verification uses the saved credential to make the draft’s read-only GET request. If you did not include validationRequest, pass --args '{"path":"/v1/me"}' to verify. Successful verification marks the connection ready and saves usage guidance. If only the test request needs correction, retry verify on the same attempt with a safe GET request in --args. To replace the credential or configuration, use the returned retryIntegrationId and the original connection scope: type-cli integrations connect custom --integration <retryIntegrationId> --scope <original-scope> --config '<nonsecret-draft>' --json --no-input. Supply the original or corrected nonsecret draft, then wait and verify the new attempt.

Once ready, use the integration ID to request data:

type-cli integrations request --integration orgint_123 \
  --args '{"path":"/v1/items"}' --json --no-input

Type injects the credential and returns a bounded, redacted response. Writes require approval and --yes. Check provider state before retrying a write if its outcome is uncertain. The CLI also supports the normal integration permission and disconnect commands for Custom APIs.

Connect a catalog provider

Type also maintains a catalog of known providers. In chat, ask AI to connect the provider by name. Type opens the provider’s connection card with known fields and documentation already filled in.

When a provider supports more than one authentication method, use the Auth method dropdown to choose one. The catalog’s recommended method is selected first, but it is a starting choice rather than a restriction; for example, you can switch from OAuth to an API token when the provider supports both.

For a customer-owned OAuth app, create or open an OAuth client in the provider and register this redirect URL:

{server}/api/oauth/integrations/callback

Replace {server} with the server URL shown in Type’s connection form, then enter the OAuth client’s ID and secret. Type pre-fills known authorization URLs, token URLs, and scopes. If the catalog does not know them, enter the provider’s HTTPS endpoints and space-separated scopes. Type uses the catalog configuration for PKCE, client authentication, and token request formatting. Connecting starts the provider’s OAuth consent flow.

Some providers also ask for an account-specific value, such as a Zendesk subdomain or NetSuite account ID. Type uses that value to fill placeholders in the API, authorization, and token URLs; the generated URLs are shown as read-only fields.

In catalog credential forms, the base URL can be optional. If it is missing, Type still saves any notes and uploaded reference files so AI can discover the correct API host during first-use setup. OAuth consent forms require the provider endpoints before starting authorization; known endpoints are filled from the catalog and your account details.

Reconnect an OAuth connection

Open the connection’s details and choose Reconnect under Manage app to renew an authorization-code OAuth credential in place. Type keeps the connection, its base URL, and its settings, reuses the saved client ID and secret, and opens the provider’s consent flow directly. If the saved secret cannot be reused (for example after you rotated it), a form asks for the new secret first. For Google APIs, Type requests offline access and always shows the consent screen so that a refresh token is issued. If a provider returns a short-lived access token without a refresh token, the connection is rejected instead of expiring silently after its first use.

First-use setup

The first time AI uses a newly saved or unfinished custom API connection, it:

1. Reads the saved provider details and available documentation.
2. Determines the API host and authentication shape.
3. Validates the requested operation with a safe, representative read in its managed sandbox.
4. Saves the working base URL and request adapter.
5. Generates usage guidance for future calls.

This setup uses run_integration_command. Type makes the credential available only to the managed command and restricts credential delivery to the approved API host. AI should not ask you to reveal the credential in chat.

Type supplies general API instructions and available provider-specific guidance before setup and on later integration searches. These instructions ask AI to check official documentation and distinguish invalid credentials from endpoint-specific permissions before requesting broader access. A successful metadata request does not prove access to database rows or reports.

After setup succeeds, later turns reuse the saved adapter and guidance. Supplied documentation is retained alongside verified request evidence; untested operations and unresolved limitations should remain explicit.

Additional information

Sometimes AI learns that a provider needs another value after the primary credential is saved. Examples include a second secret, account identifier, region, project, or authentication format.

In that case, the thread shows an Input needed card. Select Provide details to open a focused form. The form can include text fields, URLs, checkboxes, radio buttons, dropdowns, and multi-select controls. Sensitive fields are stored as encrypted credentials; non-sensitive settings are saved on the connection.

Submitting the form lets AI continue the same setup turn. The saved form is also reused when you edit the integration or connect the same provider again in the organization.

Vimeo pre-fills https://api.vimeo.com as the API base URL and validates authenticated member access with GET /me. You can optionally save the numeric Vimeo team owner ID so AI can use owner-scoped video and folder endpoints without asking for it again. For transcripts, Type first lists /videos/{video_id}/texttracks, then fetches timestamped segments from /videos/{video_id}/transcripts/{texttrack_id}.

API docs

Give AI enough API context to make the right requests:

• Add the public or internal docs URL if one exists.
• Upload Markdown or text API notes for private or internal APIs.
• Enter short usage notes in API description under Documentation (optional) without creating a file.
• Include endpoint paths, required query parameters, request bodies, response shapes, and examples.

Uploaded docs can be .md or .txt files. Keep them focused on the endpoints AI should actually use.

How AI calls the API

AI searches its available integrations before making a custom API request. The search result tells it whether first-use setup is still required and includes the saved usage guidance when setup is complete.

Newly finalized and adapter-backed connections use run_integration_command in the managed sandbox. Existing adapterless connections remain compatible with api_get and api_request; Type does not force them onto the new execution path.

AI follows the saved guidance for that specific connection. This preserves existing integrations while allowing new provider connections to learn and save a reusable request shape.

Practical guidance

• Let first-use setup begin with a safe, read-only request.
• Add API docs before asking AI to use a complex endpoint.
• Keep one custom API connection scoped to one service.
• Use personal scope for credentials only you should use; use organization scope only when the credential is intended to be shared.
• Use skills to document repeatable workflows for how AI should use the API.