> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackone.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a connector > Creates a custom connector in the current project's registry. It is owned by this project and is not available to the organization's other projects. ## OpenAPI ````yaml post /v2/connectors openapi: 3.1.0 info: title: StackOne description: The documentation for the StackOne API version: 1.0.0 contact: {} servers: - url: https://api.stackone.com security: [] tags: - name: Accounts description: View and manage linked accounts. - name: Connector Profiles description: View and manage connector profiles for the project. - name: Connectors description: Retrieve metadata for connectors. - name: Webhooks description: Configure and manage webhooks. - name: Data Sync description: View data-sync configs, schedules, and runs. paths: /v2/connectors: post: tags: - Connectors summary: Create a connector description: >- Creates a custom connector in the current project's registry. It is owned by this project and is not available to the organization's other projects. operationId: create_connector parameters: - name: expand required: false in: query description: >- Comma-separated fields to resolve on the created connector, with the same tokens as the get endpoint: `actions`, `versions`, `changelog`, `accounts_count`, `connector_profiles_count`. Unexpanded fields are `null`. schema: type: string nullable: true requestBody: required: true description: >- Exactly one of the two source-specific shapes: create from a remote MCP server url, or register a StackOne connector YAML definition. content: application/json: schema: oneOf: - title: CreateMcpConnectorRequest type: object additionalProperties: false required: - mcp_server_url properties: mcp_server_url: type: string format: uri pattern: ^https?:// description: >- The URL of the remote MCP server to create the connector for. The server is probed to determine how it authenticates (openly, with a static access token, or through OAuth). The connector is created without actions; its tools are added separately. title: type: string minLength: 1 description: >- The display name of the connector; it also derives the connector key. Defaults to the name the MCP server reports about itself, or to the server URL hostname. force: type: boolean enum: - false description: >- Not supported when creating from an MCP server url; accepted only as `false`, which is a no-op. - title: CreateYamlConnectorRequest type: object additionalProperties: false required: - yaml properties: yaml: type: string minLength: 1 description: >- The StackOne connector YAML definition to register. Its version must be new and semver-greater than the latest one, unless `force` is set. force: type: boolean default: false description: >- Skips the version-increment validation when re-registering a connector (version conflicts are still rejected while the project has immutable versioning on, its default). responses: '201': description: The connector was created. content: application/json: schema: $ref: '#/components/schemas/ConnectorDetailResource' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized access. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '408': description: The request has timed out. headers: Retry-After: description: A time in seconds after which the request can be retried. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RequestTimedOutResponse' '409': description: Conflict with current state. content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '422': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' '500': description: Server error while executing the request. content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' '501': description: This functionality is not implemented. content: application/json: schema: $ref: '#/components/schemas/NotImplementedResponse' '502': description: Bad gateway error. content: application/json: schema: $ref: '#/components/schemas/BadGatewayResponse' security: - basic: [] components: schemas: ConnectorDetailResource: type: object properties: key: type: string description: The connector key (e.g. `workday`). name: type: string description: The human-readable connector name (e.g. `Workday`). logo_url: type: string description: The URL of the connector's logo. description: type: string nullable: true description: The connector description; `null` when the connector declares none. categories: description: The categories the connector belongs to (e.g. `["hris"]`). type: array items: type: string authentication_methods: description: >- One-line summaries of the authentication methods the connector supports. type: array items: $ref: '#/components/schemas/ConnectorAuthenticationSummaryResource' version: type: string description: The connector version. owner: type: string description: The owner of the connector. release_stage: type: string description: The release stage of the connector (e.g. `ga`, `beta`). actions_count: type: integer description: >- The number of actions the connector exposes to the organization; 0 when the connector does not report action counts. events_count: type: integer description: >- The number of event actions the connector exposes; 0 when the connector does not report event counts. accounts_count: type: integer nullable: true description: >- The number of accounts linked to the connector in this project. Only resolved when `expand=accounts_count` is requested; `null` otherwise. connector_profiles_count: type: integer nullable: true description: >- The number of connector profiles configured for the connector in this project. Only resolved when `expand=connector_profiles_count` is requested; `null` otherwise. documentation_url: type: string nullable: true description: >- The URL of the public StackOne documentation for the connector; `null` when no public documentation is available. authentication: type: object additionalProperties: type: object description: >- The environments of the authentication method (`default` plus concrete environments such as `production`), keyed by environment. additionalProperties: $ref: '#/components/schemas/ConnectorAuthenticationMethodResource' description: >- The authentication methods the connector supports, keyed by authentication config key and then by environment. Contains field definitions, notices and OAuth metadata — never credential values. actions: nullable: true description: >- The metadata of the actions the connector exposes (id, label, description, tags, required scopes…). Only resolved when `expand=actions` is requested; `null` otherwise. When `connector_profile_id` is supplied, the actions that profile enables come first and every action carries `enabled`. type: array items: $ref: '#/components/schemas/ConnectorActionResource' enabled_actions_count: type: integer nullable: true description: >- How many of the connector's actions the connector profile given in `connector_profile_id` enables, out of `actions_count`. Only resolved when `connector_profile_id` is supplied together with `expand=actions`; `null` otherwise. event_actions: nullable: true description: >- The metadata of the event actions the connector exposes. Only resolved when `expand=actions` is requested; `null` otherwise. type: array items: $ref: '#/components/schemas/ConnectorEventActionResource' versions: nullable: true description: >- The registry versions of the connector, newest first — the version options a connector profile can be pinned to. Only resolved when `expand=versions` is requested; `null` otherwise. Empty for connectors with no registry versions. type: array items: $ref: '#/components/schemas/ConnectorVersionResource' changelog: nullable: true description: >- The connector's release history: one entry per published version, newest first, with its summary, labels, release date and affected actions. Only resolved when `expand=changelog` is requested, and only for StackOne's built-in Falcon connectors; `null` otherwise, including connectors with no published changelog. allOf: - $ref: '#/components/schemas/ConnectorChangelogResource' required: - key - name - logo_url - description - categories - authentication_methods - version - owner - release_stage - actions_count - events_count - documentation_url - authentication - actions - enabled_actions_count - event_actions - versions - changelog BadRequestResponse: type: object properties: statusCode: type: number description: HTTP status code example: 400 message: type: string description: Error message example: Bad Request timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time data: description: Error details nullable: true allOf: - $ref: '#/components/schemas/UnifiedError' provider_errors: description: List of provider-specific errors nullable: true type: array items: $ref: '#/components/schemas/ProviderError' required: - statusCode - message - timestamp UnauthorizedResponse: type: object properties: statusCode: type: number description: HTTP status code example: 401 message: type: string description: Error message example: Unauthorized timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp ForbiddenResponse: type: object properties: statusCode: type: number description: HTTP status code example: 403 message: type: string description: Error message example: Forbidden resource timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp NotFoundResponse: type: object properties: statusCode: type: number description: HTTP status code example: 404 message: type: string description: Error message example: Not Found timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp RequestTimedOutResponse: type: object properties: statusCode: type: number description: HTTP status code example: 408 message: type: string description: Error message example: Request timed out timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp ConflictResponse: type: object properties: statusCode: type: number description: HTTP status code example: 409 message: type: string description: Error message example: Conflict timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp UnprocessableEntityResponse: type: object properties: statusCode: type: number description: HTTP status code example: 422 message: type: string description: Error message example: Unprocessable Entity timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp TooManyRequestsResponse: type: object properties: statusCode: type: number description: HTTP status code example: 429 message: type: string description: Error message example: Too many requests timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp InternalServerErrorResponse: type: object properties: statusCode: type: number description: HTTP status code example: 500 message: type: string description: Error message example: Internal server error timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp NotImplementedResponse: type: object properties: statusCode: type: number description: HTTP status code example: 501 message: type: string description: Error message example: Not Implemented timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp BadGatewayResponse: type: object properties: statusCode: type: number description: HTTP status code example: 502 message: type: string description: Error message example: Bad Gateway timestamp: type: string description: Timestamp when the error occurred example: '2023-05-30T00:00:00.000Z' format: date-time required: - statusCode - message - timestamp ConnectorAuthenticationSummaryResource: type: object properties: key: type: string description: The key of the authentication method (e.g. `oauth2`). label: type: string description: The display label of the method (e.g. `OAuth v2`). type: type: string description: The authentication type (e.g. `oauth2`, `oidc`, `custom`). required: - key - label - type ConnectorAuthenticationMethodResource: type: object properties: type: type: string description: The authentication type (`oauth2`, `oidc` or `custom`). label: type: string description: >- The display label of the method (present on the `default` environment). nullable: true envLabel: type: string description: >- The display label of the environment (present on concrete environments). nullable: true guide: description: The guide attached to the method. nullable: true allOf: - $ref: '#/components/schemas/ConnectorAuthGuideResource' setup: description: The setup fields and notices the method requires. nullable: true allOf: - $ref: '#/components/schemas/ConnectorAuthSetupResource' fields: description: >- The config fields of the method (rendered outside the setup section). nullable: true type: array items: $ref: '#/components/schemas/ConnectorSetupFieldResource' notices: description: Notices rendered alongside the config fields. nullable: true type: array items: $ref: '#/components/schemas/ConnectorAuthNoticeResource' configuredTestActionIds: description: The ids of the test actions configured for the method. nullable: true type: array items: type: string credentialsVerifiedByAuth: type: boolean description: >- Whether completing the authentication flow already verifies credentials. nullable: true hasInlineTestAction: type: boolean description: Whether the method declares an inline test action. nullable: true required: - type ConnectorActionResource: type: object properties: id: type: string description: The unique id of the action. label: type: string description: The display label of the action. description: type: string description: The description of the action. schema_type: type: string description: The schema type of the action (e.g. `list`, `create`). tags: description: The tags of the action. nullable: true type: array items: type: string required_scopes: description: The provider scopes the action requires. nullable: true type: array items: type: string release_stage: type: string description: The release stage of the action (e.g. `ga`, `beta`). nullable: true effects: description: The effects of the action (e.g. `read`, `write`, `delete`). nullable: true type: array items: type: string annotations: description: The behavioural annotations of the action. nullable: true allOf: - $ref: '#/components/schemas/ConnectorActionAnnotationsResource' action_details: type: object additionalProperties: true description: >- The full action definition (inputs, response schema…). A large, connector-specific payload. nullable: true authentication: description: The authentication methods the action supports. type: array items: $ref: '#/components/schemas/ConnectorActionAuthUsageResource' syncable: type: boolean description: Whether this action can be synced by the data-sync engine. nullable: true supports_incremental: type: boolean description: >- Whether this action supports incremental syncs (it declares an incremental strategy). nullable: true has_required_parameters: type: boolean description: >- Whether this action requires parameters to be supplied when it is synced. Such actions cannot be linked automatically for every account — each schedule must be created with its parameter values. nullable: true enabled: type: boolean description: >- Whether the connector profile given in `connector_profile_id` enables this action. Present only when the request names a connector profile. nullable: true required: - id - label - description - schema_type - authentication ConnectorEventActionResource: type: object properties: id: type: string description: The unique id of the event action. label: type: string description: The display label of the event action. description: type: string description: The description of the event action. tags: description: The tags of the event action. nullable: true type: array items: type: string release_stage: type: string description: The release stage of the event action (e.g. `ga`, `beta`). nullable: true requires_manual_setup: type: boolean description: >- Whether the event requires manual webhook setup in the external system. nullable: true authentication: description: The authentication methods the event action supports. nullable: true type: array items: $ref: '#/components/schemas/ConnectorActionAuthUsageResource' required: - id - label - description ConnectorVersionResource: type: object properties: version: type: string description: The connector version (e.g. `1.2.0`). owner: type: string description: The owner of the version; `stackone` for built-in connectors. builtin: type: boolean description: >- Whether the version is a built-in StackOne connector (`true`) or one owned by the organization (`false`). release_stage: type: string description: The release stage of the version (e.g. `ga`, `beta`). required: - version - owner - builtin - release_stage ConnectorChangelogResource: type: object properties: current_version: type: string description: The most recent version with a changelog entry. entries: description: >- One entry per published version, newest first by version (semver descending). type: array items: $ref: '#/components/schemas/ConnectorChangelogEntryResource' required: - current_version - entries UnifiedError: type: object properties: statusCode: type: number description: HTTP status code example: 400 nullable: true message: type: string description: Error message example: Bad Request nullable: true headers: type: object description: Response headers example: content-type: application/json x-request-id: 5678c28b211dace4e0a0f9171e6b88c5 nullable: true ProviderError: type: object properties: status: type: number description: HTTP status code of the provider error example: 400 nullable: true url: type: string description: URL that caused the error example: https://api.provider.com/v1/resource nullable: true raw: type: object description: Raw error response from the provider example: message: Invalid input parameters nullable: true headers: type: object description: Response headers example: content-type: application/json x-request-id: 5678c28b211dace4e0a0f9171e6b88c5 nullable: true ConnectorAuthGuideResource: type: object properties: description: type: string description: A description of the method. nullable: true supportLink: type: string description: A link to the setup documentation for the method. nullable: true ConnectorAuthSetupResource: type: object properties: fields: description: The setup fields the method requires. nullable: true type: array items: $ref: '#/components/schemas/ConnectorSetupFieldResource' notices: description: Notices rendered alongside the setup fields. nullable: true type: array items: $ref: '#/components/schemas/ConnectorAuthNoticeResource' ConnectorSetupFieldResource: type: object properties: key: type: string description: The key the field value is submitted under. label: type: string description: The display label of the field. nullable: true type: type: string description: The input type of the field (e.g. `text`, `password`, `select`). nullable: true required: type: boolean description: Whether the field is required. nullable: true secret: type: boolean description: >- Whether the field value is a secret — submitted via `secrets` and returned redacted. nullable: true readOnly: type: boolean description: Whether the field is read-only. nullable: true options: description: The options of a select-type field. nullable: true type: array items: $ref: '#/components/schemas/ConnectorFieldOptionResource' placeholder: type: string description: The placeholder text of the field. nullable: true externalSystemAccountIdentifier: type: boolean description: >- Whether the field value identifies the account in the external system (used for event routing). nullable: true value: type: string description: The default or fixed value of the field. nullable: true computed: type: boolean description: >- Whether the field value is computed server-side rather than user-provided. nullable: true guide: description: Guide texts for the field. nullable: true allOf: - $ref: '#/components/schemas/ConnectorFieldGuideResource' required: - key ConnectorAuthNoticeResource: type: object properties: key: type: string description: The unique key of the notice. type: type: string description: The notice type (`warning` or `info`). description: type: string description: The notice text. position: type: string description: Where the notice is rendered (`top` or `bottom`). nullable: true anchor: type: string description: The key of the field the notice is anchored to. nullable: true required: - key - type - description ConnectorActionAnnotationsResource: type: object properties: title: type: string description: A human-readable title for the action. nullable: true readOnlyHint: type: boolean description: Whether the action does not modify the external system. nullable: true destructiveHint: type: boolean description: Whether the action may perform destructive updates. nullable: true idempotentHint: type: boolean description: >- Whether repeated calls with the same arguments have no additional effect. nullable: true openWorldHint: type: boolean description: >- Whether the action interacts with entities outside the external system. nullable: true ConnectorActionAuthUsageResource: type: object properties: type: type: string description: The authentication type (e.g. `oauth2`, `custom`). label: type: string description: The display label of the authentication method. key: type: string description: The key of the authentication method. required_scopes: description: The provider scopes the action requires under this method. nullable: true type: array items: type: string description: type: string description: A description of the authentication requirements. nullable: true required: - type - label - key ConnectorChangelogEntryResource: type: object properties: version: type: string description: The connector version the entry describes (e.g. `1.2.0`). summary: type: string description: A summary of what changed in this version. labels: nullable: true description: >- Labels categorising the change (e.g. `new-actions`, `bug-fix`); `null` when the entry carries none. type: array items: type: string released_at: type: string format: date-time description: When the version was released, as an ISO 8601 timestamp. affected_actions: nullable: true description: >- The action ids this version added, removed and changed relative to the previous version; `null` when no previous version exists to compare against (a connector's first recorded entry). allOf: - $ref: '#/components/schemas/ConnectorChangelogAffectedActionsResource' required: - version - summary - labels - released_at - affected_actions ConnectorFieldOptionResource: type: object properties: label: type: string description: The display label of the option. value: type: string description: The value submitted when the option is selected. required: - label - value ConnectorFieldGuideResource: type: object properties: tooltip: type: string description: A short tooltip for the field. nullable: true description: type: string description: A longer description of how to fill the field. nullable: true ConnectorChangelogAffectedActionsResource: type: object properties: added: description: The ids of the actions this version added. type: array items: type: string removed: description: The ids of the actions this version removed. type: array items: type: string changed: description: The ids of the actions this version changed. type: array items: type: string required: - added - removed - changed securitySchemes: basic: type: http scheme: basic ````