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 other credential, unless the API is unauthenticated.
• The API’s HTTPS base URL or documentation URL. A plain custom API requires at least one of these.
• Optional API notes or .md / .txt reference files.

Do not paste API keys into Space instructions, skills, or thread messages. Put credentials in the connection form 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 base URL, documentation URL, or both.
5. Enter the secret key, or mark the API as unauthenticated.
6. Optionally upload API reference files or expand API description to add notes.
7. Choose whether the connection is available to your organization or only to you.
8. Save the connection.

Saving stores the connection without requiring a live test request. AI completes setup when it first uses the connection.

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 Authentication method switcher 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. Advanced OAuth settings control PKCE, whether the token endpoint receives client credentials in request parameters or an HTTP Basic header, and whether the token request is form-encoded or JSON.

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.

The base URL is optional for a catalog provider. If it is missing, AI discovers the correct API host from provider documentation during first-use setup.

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. Runs one safe request 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.

After setup succeeds, later turns reuse the saved adapter and guidance instead of rediscovering the API.

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.
• Expand API description to add short usage notes 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.