Skip to main content
Cohere

Search documentation

Type to search this documentation.

Create a Connector

POST/v1/connectorsCreate a Connector

Creates a new connector. The connector is tested during registration and will cancel registration when the test is unsuccessful. See 'Creating and Deploying a Connector' for more information.

Parameters

X-Client-Namestringheader

The name of the project that is making the request.

Request body

required
application/json
objectCreateConnectorRequest
activeboolean

Whether the connector is active or not.

default true

continue_on_failureboolean

Whether a chat request should continue or not if the request to this connector fails.

default false

descriptionstring

A description of the connector.

excludesarray of string

A list of fields to exclude from the prompt (fields remain in the document).

Show child attributes
namestringrequired

A human-readable name for the connector.

oauthobject
Show child attributes
authorize_urlstring

The OAuth 2.0 /authorize endpoint to use when users authorize the connector.

client_idstring

The OAuth 2.0 client ID. This fields is encrypted at rest.

client_secretstring

The OAuth 2.0 client Secret. This field is encrypted at rest and never returned in a response.

scopestring

The OAuth scopes to request when users authorize the connector.

token_urlstring

The OAuth 2.0 /token endpoint to use when users authorize the connector.

service_authobject
Show child attributes
tokenstringrequired

The token that will be used in the HTTP Authorization header when making requests to the connector. This field is encrypted at rest and never returned in a response.

typestringrequired

The token_type specifies the way the token is passed in the Authorization header. Valid values are "bearer", "basic", and "noscheme".

one of "bearer", "basic", "noscheme" · default "noscheme"

urlstringrequired

The URL of the connector that will be used to search for documents.

Example request
{
  "active": true,
  "continue_on_failure": false,
  "description": "string",
  "excludes": [
    "string"
  ],
  "name": "string",
  "oauth": {
    "authorize_url": "string",
    "client_id": "string",
    "client_secret": "",
    "scope": "string",
    "token_url": "string"
  },
  "service_auth": {
    "token": "string",
    "type": "noscheme"
  },
  "url": "string"
}

Responses

200OKapplication/json
objectCreateConnectorResponse
connectorobjectrequired

A connector allows you to integrate data sources with the '/chat' endpoint to create grounded generations with citations to the data source. documents to help answer users.

Show child attributes
activeboolean

Whether the connector is active or not.

auth_statusstring

The OAuth status for the user making the request. One of ["valid", "expired", ""]. Empty string (field is omitted) means the user has not authorized the connector yet.

one of "valid", "expired"

auth_typestring · enum

The type of authentication/authorization used by the connector. Possible values: [oauth, service_auth]

continue_on_failureboolean

Whether a chat request should continue or not if the request to this connector fails.

created_atstring · date-timerequired

The UTC time at which the connector was created.

descriptionstring

A description of the connector.

excludesarray of string

A list of fields to exclude from the prompt (fields remain in the document).

Show child attributes
idstringrequired

The unique identifier of the connector (used in both `/connectors` & `/chat` endpoints). This is automatically created from the name of the connector upon registration.

namestringrequired

A human-readable name for the connector.

oauthobject
Show child attributes
authorize_urlstringrequired

The OAuth 2.0 /authorize endpoint to use when users authorize the connector.

client_idstring

The OAuth 2.0 client ID. This field is encrypted at rest.

client_secretstring

The OAuth 2.0 client Secret. This field is encrypted at rest and never returned in a response.

scopestring

The OAuth scopes to request when users authorize the connector.

token_urlstringrequired

The OAuth 2.0 /token endpoint to use when users authorize the connector.

organization_idstring

The organization to which this connector belongs. This is automatically set to the organization of the user who created the connector.

updated_atstring · date-timerequired

The UTC time at which the connector was last updated.

urlstring

The URL of the connector that will be used to search for documents.

Example response
{
  "connector": {
    "active": true,
    "auth_status": "expired",
    "auth_type": "string",
    "continue_on_failure": true,
    "created_at": "2026-06-09T00:00:00Z",
    "description": "string",
    "excludes": [
      "string"
    ],
    "id": "string",
    "name": "string",
    "oauth": {
      "authorize_url": "string",
      "client_id": "string",
      "client_secret": "",
      "scope": "string",
      "token_url": "string"
    },
    "organization_id": "string",
    "updated_at": "2026-06-09T00:00:00Z",
    "url": "string"
  }
}
400This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
401This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
403This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
404This error is returned when a resource is not found. This could be because: - The endpoint does not exist - The resource does not exist eg model id, dataset id application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
422This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
429Too many requestsapplication/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
498This error is returned when a request or response contains a deny-listed token. application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
499This error is returned when a request is cancelled by the user. application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
500This error is returned when an uncategorised internal server error occurs. application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
501This error is returned when the requested feature is not implemented. application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
503This error is returned when the service is unavailable. This could be due to: - Too many users trying to access the service at the same time application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
504This error is returned when a request to the server times out. This could be due to: - An internal services taking too long to respond application/json
object
idstring
messagestring
Example response
{
  "id": "string",
  "message": "string"
}
Documentation menu