# Register a connector

Fetches the source, parses it, dispatches to the plugin that owns it, and syncs the tool catalog — one call. Passing a `presetId` from the catalog resolves the source for you.

## POST `/v1/connectors`

### Authorization

`Authorization` Bearer token · header required

```
Authorization: Bearer <token>
```

with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

### Scopes: `connectors:write`

## Query parameters

`team` string

min length 1 · max length 255

## Request body

required `application/json`

- `slug` string required
  - Team-unique slug. Also the namespace its tools hang off, so keep it short.
  - min length 1 · max length 64 · matches `^[a-z0-9][a-z0-9-]*$`

- `title` string required
  - Display name. Defaults to whatever the source calls itself.
  - min length 1 · max length 255

- `description` string
  - What this connector reaches, in one line. Agent-visible.
  - max length 1000

- `presetId` string
  - Catalog row to add. Skips fetching and analyzing the source — everything else is optional when set.
  - min length 1

- `source` object
  - Required unless `presetId` names a catalog row that carries it.

### Show properties Hide properties

One of:

- object
  - `kind` string required
  - `specUrl` string <uri>
  - URL of the OpenAPI document to fetch.
  - `spec` object
  - Inline OpenAPI document, when there is no URL to fetch.
  - `baseUrl` string <uri>
  - Override the server URL the spec declares.

- object
  - `kind` string required
  - `endpoint` string <uri> required
  - GraphQL endpoint to introspect.

- object
  - `kind` string required
  - `endpoint` string <uri> required
  - Remote MCP endpoint. stdio servers cannot be reached from a hosted product.

## `authMethods` object[]
- Omit to derive authentication from the source's own declared security schemes.

### Show properties Hide properties

Array of `object`

One of:

- object
  - `kind` string required
  - `slug` string required
  - Names this method when a connector offers more than one.
  - `label` string required
  - What to call it in a connect form, in the provider's own words.

- object
  - `kind` string required
  - `slug` string required
  - Names this method when a connector offers more than one.
  - `label` string required
  - What to call it in a connect form, in the provider's own words.
  - `scopes` string[] required
  - Scopes requested at authorization unless the caller narrows them.
  - `dynamicRegistration` boolean required
  - Whether the provider supports RFC 7591 dynamic client registration, so no client has to be pre-created.

## Responses

### 201 Response for status 201

```json
{
  "$schema": "string<uri>",
  "data": {
    "slug": "string",
    "title": "string",
    "description": "string | any",
    "source": "string required",
    "sourceUrl": "string | any required",
    "firstParty": "boolean required",
    "presetId": "string | any required",
    "authMethods": [
      {
        "kind": "string required",
        "slug": "string required",
        "label": "string required"
      }
    ],
    "toolCount": "integer required",
    "connections": [
      {
        "id": "string required",
        "connector": "string required",
        "owner": "string required",
        "displayName": "string required",
        "description": "string | any required",
        "status": "string required",
        "identityLabel": "string | any required",
        "credentialConfigured": "boolean required",
        "authMethod": "string | any required",
        "scopes": [
          "string required"
        ],
        "isDefault": "boolean required",
        "toolCount": "integer required",
        "createdBy": "string | any required",
        "lastCheckedAt": "string<date-time> | any required",
        "revokedAt": "string<date-time> | any required",
        "createdAt": "string<date-time> required",
        "updatedAt": "string<date-time> required"
      }
    ],
    "specSyncedAt": "string<date-time> | any required",
    "createdAt": "string<date-time> required",
    "updatedAt": "string<date-time> required"
  }
}
```

### Error response document

```json
{
  "$schema": "http://example.com",
  "type": "string required",
  "title": "string required",
  "status": "integer required",
  "detail": "string required",
  "code": "string required",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string required"
}
```

### Try it

## Server

Base URL: https://api.spacefast.com
Custom base URL:
Overrides the selected server when set.