> ## Documentation Index > Fetch the complete documentation index at: https://docs.versori.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Action > CreateAction creates a new Action for the specified ConnectorVersion. The Action type must be compatible with the protocol of the Connector, otherwise a 400 Bad Request response will be returned. ## OpenAPI ````yaml post /o/{organisation_id}/connectors/{connector_id}/versions/{version}/actions openapi: 3.1.0 info: title: Versori Connect API version: 0.0.1 license: name: UNLICENSED identifier: UNLICENSED description: > Connect API allows you to connect to your external systems to the Versori Platform. The main component of the Connect API are Connectors. Connectors are split into the following components: - Protocol - Authentication Scheme - Connections - Global Parameters - Actions - Triggers - Definitions ## Protocol The protocol defines the transport mechanism used to communicate with your external system. Currently, only HTTP/REST APIs are supported within Connect API, however our legacy "Apps" functionality is available on [Switchboard API](/api-reference/switchboard-api) which supports GraphQL APIs and SOAP web services. ## Authentication Scheme The authentication scheme defines how the Versori Platform will authenticate with your external system. Different schemes are applicable to different protocols. ### HTTP The following authentication schemes are supported for HTTP: - OAuth 2.0 - OIDC - API Key (in header, query or cookie) - Basic - Bearer ## Connections Each Connector has at least one connection and additional connections can be added. Connections are used to connect to different instances of your external system. For example, you may have a development, staging and production connection, each with different credentials and addresses. Each Connection must provide a Credential which satisfies one authentication scheme for the Connector. Connections can define variables, which can be used to customise certain aspects of the Connector such as default values for certain fields/parameters. Finally, some protocols may require specific configuration for each connection. For example, the HTTP Protocol requires a base URL for each connection. ## Global Parameters Global Parameters allows a user to configure a set of parameters which can be used across multiple Actions. Within the UI, whenever a user starts to create a new Action the UI will pre-populate the Action with the Global Parameters. If the Action in question does not require any of these parameters the user may delete them before saving. When a user creates, updates or deletes a global parameter, the user will be prompted to choose which Actions should reflect the change, with the ability to choose all, some or none. ### HTTP Parameters For HTTP Connectors, the following parameter types may be set as Global Parameters: - Path parameters - Query parameters - Headers ## Actions Actions define the actions that can be performed on your external system. An action may be defined and implemented differently depending on the protocol. For example, an HTTP Action contains a method like GET, PUT, POST etc., whereas a BigQuery Actions will contain a SQL query. ### HTTP For HTTP Connectors, each Action defines a single HTTP request. The Action can contain inputs to customise the request, some inputs may also allow default values which can be overridden when used within other Versori products. Default values can be defined using connection variables. The supported HTTP inputs are: - Path parameters - Query parameters - Headers - Request body Definitions (one per supported media-type) The Action can also define outputs: - Headers - Status Codes, and their associated Response body Definitions (one per supported media-type) ### BigQuery SQL BigQuery SQL Actions are defined as SQL queries. The query can contain parameters to customise the query at runtime, for example in Switchboard a user may use literal values or Selectors to provide the parameters. This functionality is provided via the [query](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query) API endpoint. When creating a BigQuery SQL Action, the associated Definition is automatically created based on the query. ## Triggers Triggers define how the Versori Platform will be notified of events from your external system. Each Protocol determines how Triggers are defined since how they are implemented may vary. ### HTTP Triggers These are essentially webhooks, which an external service may invoke to notify the Versori Platform of an event. They are modelled similarly to HTTP Actions, but Versori expects a certain request and allows the user to configure the response. In the future, you will also be able to define HTTP Trigger Lifecycles, which define how a webhook is created/deleted on the external system when a Switchboard integration is published/unpublished. However, this is out of scope for the initial release. ## Definitions Definitions provide the Versori Platform the information required to validate and provide auto-complete behaviour when dealing with input/output data between connectors. Each definition has a media-type and an associated schema. Which schema implementation is used depends on the media-type, we initially support the following: - `application/json`, defined by JSON Schemas. - `text/xml`, defined by XML Schema Definitions (XSDs). - `text/csv`, how this is defined isn't known yet, however there are discussions in JIRA about this. ## Versioning Except for the top-level Connector data and their Connections, other aspects of a Connector such as Actions, Triggers and Definitions are versioned resources. A connector can have multiple versions and each version can either be in "draft" or "published" state. A version is published if its `publishedAt` field is not null. Versions are defined as an arbitrary string, but users are encouraged to follow a consistent versioning scheme such as SemVer, CalVer, or an incrementing number. Connectors may only be used by Versori products if they are published, and once published they are immutable. If an edit is attempted against a published version then an error will be returned. Unpublished Connectors are considered to be in "draft" and can be edited as many times as required. Connectors may be unpublished, but only when they are not referenced by any other system (see [Subscribers](#Subscribers) below). ### Special Versions There are two reserved words to reference a published version, "latest" and "default". "latest" will always return the latest published version according to it's `publishedAt` field, whereas "default" will return the version which has been set as such by the user. If the user never specifies a default version, the "latest" published version will be used. ### Publishing Versions When a new version is published, the user should be prompted to choose how Versori products should handle the update. For example, for Switchboard the user should be able to choose whether to update existing integrations to use the new version, or to leave them as they are. To facilitate this UX the Connect API has the concept of subscriptions (is there a better name?) where other APIs can register their interest in a Connector. ## Subscribers A Connector has the concept subscribers, where other products can notify the Connect API of their interest in that connector. This allows the Connect API to check whether a Connector is being used by other products and prevent deletion if so. ### Switchboard When a board is published, the Switchboard orchestrator will subscribe to the Connector. When that board is then unpublished, the orchestrator will unsubscribe from the Connector. ## Completions Coming Soon Completions is an advanced feature of the Connect API which enables Connector authors to define how a particular field within a Definition may be auto-completed. This is useful for fields which are almost always a fixed value but whose valid values are determined by how the external system is configured. i.e. the `channel` field in a Slack `postMessage` call must be a valid channel name for the Slack Workspace in which the Connector is connecting to. There are different mechanisms for defining Completions which are described below. ### Static Completions Static Completions are defined by the Connector author and are a fixed list of values. For JSON Definitions, this is automatically generated by properties with the `enum` keyword. Other media-types will have their own mechanisms which may or may not be directly supported by their schema implementation. ### Remote Completions Remote Completions make a connector to an external API to retrieve the valid values for a field. Initially a Completion can be defined by choosing another Connector Action, and a transformation on how to extract the values to present to the user. servers: - description: Production url: https://platform.versori.com/api/connect/v1 - description: Staging url: https://platform-staging.versori.com/api/connect/v1 - description: Development url: http://localhost:8082 security: - bearerToken: [] - cookie: [] tags: - name: protocol-http description: > The HTTP Protocol allows the Connect API to communicate with external systems via HTTP requests. - name: connectors description: > Connectors are the core resource of the Connect API. They represent a connector to an external system, and contains the information required to interact with that system. - name: connector-versions description: > Connector Versions belong to a Connector and maintains the set of Actions, Triggers and Definitions for a Connector. - name: auth-schemes description: > Auth Schemes are the mechanism by which the Connect API authenticates with external systems. They define how Actions and Triggers are authenticated. Not all Auth Schemes are supported by all Protocols, you can use the [GET /auth-schemes](/api-reference/connect-api/protocols/list-auth-schemes) endpoint to determine which Auth Schemes are supported for each Protocol. - name: connections description: | Connections define how Actions and Triggers are authenticated. - name: credentials description: > Credentials are the mechanism by which the Connect API authenticates with external systems. They define how Actions and Triggers are authenticated. Which Credentials are supported depends on the Auth Scheme chosen, which again is determined by the Protocol. - name: actions description: > Actions define how the Versori Platform will interact with your external system. Each Protocol determines how Actions are defined since how they are implemented may vary. - name: triggers description: > Triggers define how the Versori Platform may receive requests from your external systems. Each Protocol determines how Triggers are defined since how they are implemented may vary. - name: definitions description: > Definitions provide the Versori Platform the information required to validate and provide auto-complete behaviour when dealing with input/output data between connectors. Each definition has a media-type and an associated schema which is compatible with that media-type, for example JSON Schema is used for `application/json` media-types. - name: protocols description: > Protocols are the mechanism by which the Connect API communicates with external systems. They define how Actions, Triggers and Definitions are implemented. - name: protocol-bigquery description: > The BigQuery Protocol allows the Connect API to communicate with BigQuery datasets via the BigQuery API. - name: misc description: | Miscellaneous endpoints which don't fit into any other category. paths: /o/{organisation_id}/connectors/{connector_id}/versions/{version}/actions: parameters: - $ref: '#/components/parameters/organisation_id' - $ref: '#/components/parameters/connector_id' - $ref: '#/components/parameters/version' post: tags: - actions summary: Create Action description: > CreateAction creates a new Action for the specified ConnectorVersion. The Action type must be compatible with the protocol of the Connector, otherwise a 400 Bad Request response will be returned. operationId: CreateAction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActionCreate' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Action' default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: organisation_id: name: organisation_id in: path required: true schema: type: string format: ulid x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid connector_id: name: connector_id in: path required: true description: ID is the unique identifier of the Connector. schema: type: string format: ulid x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid version: name: version description: > Version is the version name of the Connector to retrieve. The reserved names "latest" and "default" may be used to retrieve the latest version or the default version respectively. in: path required: true schema: type: string schemas: ActionCreate: description: ActionCreate defines a new Action to be created. discriminator: propertyName: type mapping: http: $ref: '#/components/schemas/ActionHTTPCreate' oneOf: - $ref: '#/components/schemas/ActionHTTPCreate' Action: discriminator: propertyName: type mapping: http: $ref: '#/components/schemas/ActionHTTP' oneOf: - $ref: '#/components/schemas/ActionHTTP' Error: type: object properties: code: type: string description: Code is a machine-readable error code. message: type: string description: Message is a human-readable error message. fields: type: array items: $ref: '#/components/schemas/ErrorField' x-go-type-skip-optional-pointer: true details: type: string x-go-type-skip-optional-pointer: true required: - code - message ActionHTTPCreate: description: ActionHTTPCreate defines a new HTTP Action to be created. type: object allOf: - $ref: '#/components/schemas/ActionCommon' - $ref: '#/components/schemas/ActionHTTPCommonCreate' ActionHTTP: description: ActionHTTP defines an HTTP Action. type: object allOf: - $ref: '#/components/schemas/ActionBase' - $ref: '#/components/schemas/ActionHTTPCommon' ErrorField: description: ErrorField denotes a field which has an error. type: object properties: field: type: string description: > Field is the name of the field which has an error, this may be a path to a nested field, including array elements. The format of this field is of the form: "field1.field2[0].field3" message: type: string description: Message is the error message for this specific field. required: - field - message ActionCommon: description: ActionCommon defines all the common fields for an Action. type: object properties: type: $ref: '#/components/schemas/ActionTypeEnum' name: description: > Name is a unique identifier for the Action within the scope of the Connector. It is expected to both human and machine-readable, i.e. "GetProduct" or "get_products", see the validation regex for more details. type: string regex: ^[a-zA-Z0-9_\-$]+$ x-go-type-skip-optional-pointer: true summary: type: string description: > Summary is a human-readable version of the `id` field, i.e. "Get Product" or "Get Products". This is used when displaying the Action to users, however if omitted the `actionId` can be used to display to users instead. x-go-type-skip-optional-pointer: true description: description: > Description is a human-readable description of the Action. It can provide extra information to users about how the Action operates and anything the user may need to be aware of when using it. type: string x-go-type-skip-optional-pointer: true required: - type - name ActionHTTPCommonCreate: description: ActionHTTPCommon defines the common fields for creating a HTTP Action. properties: type: type: string const: http method: $ref: '#/components/schemas/HTTPMethod' path: $ref: '#/components/schemas/ActionPath' parameters: type: array items: $ref: '#/components/schemas/ActionHTTPParameter' requestBody: $ref: '#/components/schemas/ActionHTTPRequestBodyCreate' responses: description: > Responses defines the expected responses from the HTTP endpoint. This is used to determine whether the Action was successful or not. At least one response must be defined in order for the Action to be valid. type: array items: $ref: '#/components/schemas/ActionHTTPResponseCreate' required: - type - method - path - parameters - responses ActionBase: description: | ActionBase defines all the common fields for an Action. type: object allOf: - properties: id: description: ID is the unique identifier of the Action. type: string x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid errors: description: > Errors is a list of ErrorField objects which defines the errors which may be returned by the Action. An empty array denotes that the Action has been validated and no errors were found. If this field is undefined then this means validation has not occurred. type: array items: $ref: '#/components/schemas/ActionError' x-go-type-skip-optional-pointer: true required: - id - $ref: '#/components/schemas/ActionCommon' ActionHTTPCommon: description: ActionHTTPCommon defines the common fields for all HTTP Actions. properties: type: type: string const: http method: $ref: '#/components/schemas/HTTPMethod' path: $ref: '#/components/schemas/ActionPath' parameters: type: array items: $ref: '#/components/schemas/ActionHTTPParameter' requestBody: $ref: '#/components/schemas/ActionHTTPRequestBody' responses: description: > Responses defines the expected responses from the HTTP endpoint. This is used to determine whether the Action was successful or not. type: array items: $ref: '#/components/schemas/ActionHTTPResponse' required: - type - method - path - parameters - responses ActionTypeEnum: type: string enum: - http HTTPMethod: description: > HTTPMethod defines the HTTP method which will be used when invoking the Action. This is typically one of the standard HTTP methods such as GET, POST, PUT, PATCH or DELETE, but may be any valid HTTP method. type: string enum: - GET - POST - PUT - PATCH - DELETE - HEAD - OPTIONS - CONNECT - TRACE ActionPath: description: > ActionPath is appended to the Connector's base URL to build the full URL to send requests to. It may also contain placeholders to inject dynamic values from the following sources: - `{{ param. }}` - Injects the value of the parameter with the given name. - `{{ conn. }}` - Injects the value of the connection variable with the given name. type: string ActionHTTPParameter: description: > ActionHTTPParameter defines a parameter which is sent to the HTTP endpoint when invoking the Action. This may be a query parameter, header or cookie depending on the `in` field. type: object properties: name: type: string description: >- Name is the name of the parameter which will be sent to the HTTP endpoint. in: $ref: '#/components/schemas/ActionHTTPParameterIn' required: description: Required denotes whether this parameter is required. type: boolean type: description: > Type is the type of the parameter. Currently only scalar types are supported, if you require complex types then get in touch with support to discuss options. type: string enum: - string - number - integer - boolean default: description: > Default is the default value to use for the parameter if no value is provided by the user. If this is not defined then the parameter will not be sent to the HTTP endpoint if no value is explicitly provided by the user. If this value is a string, it may be templated using a Go-formatted template string, i.e. `{{ .conn.foo }}` where `foo` is an connection variable defined in the Connector's Connection. x-go-type-skip-optional-pointer: true completion: $ref: '#/components/schemas/ActionCompletion' required: - name - in - required - type ActionHTTPRequestBodyCreate: description: > ActionHTTPRequestBody defines whether a request body is required for a particular HTTP Action, and if so which Definitions are considered valid. If this value is undefined then no request body will be sent. type: object properties: required: type: boolean description: Required denotes whether a request body is required for this Action. definitions: description: > An Action may support one Definition per media-type, i.e. application/json or application/xml etc. Attempts to link multiple Definitions with the same media-type will result in an error. type: array items: $ref: '#/components/schemas/ActionDefinitionCreate' required: - required - definitions ActionHTTPResponseCreate: description: > ActionHTTPResponseCreate is the payload to create a new response for an Action. type: object allOf: - $ref: '#/components/schemas/ActionHTTPResponseCommon' - properties: definitions: description: > An Action may support one Definition per media-type, i.e. application/json or application/xml etc. Attempts to link multiple Definitions with the same media-type will result in an error. type: array items: $ref: '#/components/schemas/ActionDefinitionCreate' required: - id - definitions ActionError: description: ActionError is the payload returned when an Action fails validation type: object properties: field: description: > Field is the field which failed validation. This is typically a JSON Pointer, i.e. "/parameters/0/properties/id", however this is open for discussion (we should be consistent with the ErrorField type). type: string message: type: string description: > Message is a human-readable description of the error. This is typically a human-readable string, i.e. "The parameter 'id' is invalid". severity: description: > Severity is the severity of the error. This is used to determine how the error should be displayed to the user, i.e. a warning may be displayed in a modal dialog, whereas an error may be displayed inline. type: string enum: - error - warning required: - field - message - severity ActionHTTPRequestBody: description: > ActionHTTPRequestBody defines whether a request body is required for a particular HTTP Action, and if so which Definitions are considered valid. If this value is undefined then no request body will be sent. type: object properties: required: type: boolean description: Required denotes whether a request body is required for this Action. definitions: description: > An Action may support one Definition per media-type, i.e. application/json or application/xml etc. Attempts to link multiple Definitions with the same media-type will result in an error. type: array items: $ref: '#/components/schemas/ActionDefinition' required: - required - definitions ActionHTTPResponse: description: > ActionHTTPResponse defines what responses may be returned by the HTTP server when invoking the Action. type: object allOf: - $ref: '#/components/schemas/ActionHTTPResponseCommon' - properties: id: type: string format: ulid x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid definitions: description: > An Action may support one Definition per media-type, i.e. application/json or application/xml etc. Attempts to link multiple Definitions with the same media-type will result in an error. type: array items: $ref: '#/components/schemas/ActionDefinition' required: - id - definitions ActionHTTPParameterIn: type: string enum: - cookie - header - path - query ActionCompletion: description: > ActionCompletion defines how an Action may be completed by Switchboard to aid the user in selecting a valid value. Schema TBD. type: object additionalProperties: false ActionDefinitionCreate: description: > ActionDefinitionCreate is used to create a new ActionDefinition using a reference to an existing Definition. type: object properties: definition: $ref: '#/components/schemas/DefinitionRef' required: - definition ActionHTTPResponseCommon: description: > ActionHTTPResponseCommon defines the common fields for an ActionHTTPResponse. type: object properties: status: description: > Status is the HTTP status code which is expected from the HTTP endpoint. If this is not defined then this response is treated as the default response, i.e. if no other response matches then this response will be used. An action may only have one default response and each response must have a unique status code. type: integer ActionDefinition: description: ActionDefinition links a Definition to an Action. type: object properties: id: description: > ID is a unique identifier for the request body within the scope of the Action. type: string format: ulid x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid definition: $ref: '#/components/schemas/Definition' required: - id - definition DefinitionRef: description: >- DefinitionRef is a reference to a Definition. It is used to link a Definition to an ActionDefinition. oneOf: - $ref: '#/components/schemas/DefinitionRefId' - $ref: '#/components/schemas/DefinitionRefName' Definition: description: > Definition describes a single definition of a type which is used by the Connector. The schema language used is dependent on the media-type of the Definition, for example JSON Schema is used for media-types application/json. type: object allOf: - type: object properties: id: description: ID is the unique identifier of the Definition. type: string format: ulid x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid required: - id - $ref: '#/components/schemas/DefinitionCommon' - type: object properties: url: description: > URL is the location of the actual Schema definition for this Definition entity. The structure of this URL will be consistent across all media types for each connection, for example: - `https://platform.versori.com/api/schemas/v1/o/{organisation_id}/{connector_id}/{connector_version}/{definition_slug}.{media_type_ext}` type: string format: uri x-go-name: URL referencedBy: description: > ReferencedBy is a list of DefinitionReference objects which defines what other entities are referencing the this Definition. type: array items: $ref: '#/components/schemas/DefinitionReference' x-go-type-skip-optional-pointer: true required: - url DefinitionRefId: description: DefinitionRefId is a reference to a Definition using its ID. type: object properties: id: description: ID is the unique identifier of the Definition. type: string format: ulid x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid required: - id DefinitionRefName: description: DefinitionRefName is a reference to a Definition using its name. type: object properties: name: description: Name is the name of the Definition. type: string required: - name DefinitionCommon: description: > DefinitionCommon is the common properties which are shared between Definitions for all of creation, retrieval and updates. properties: name: description: > Name is a unique identifier for the Definition within the scope of the Connector. It is expected to both human and machine-readable, i.e. "Product" or "product_variant". type: string regex: ^[a-zA-Z0-9_\-]+$ accept: description: > Accept indicates which content types, expressed as MIME types, that this definition can accept. This value is analogous to the Accept HTTP header, as defined in RFC 7231, section 5.3.2, except each type is defined in a separate array element, rather than as a comma-separated list. This does not represent the content type of the schema body itself, but the data which conforms to this definition. For example, an API may respond in JSON or YAML, but the schema may be a YAML-formatted JSON Schema. In this case, the Definition's `accept` field could be `["application/json", "text/yaml"]` and `schema.contentType` will be `application/schema+yaml`. type: array items: type: string description: description: > Description is a human-friendly description of the Definition. This is typically used to describe the purpose of the Definition and how it should be used. type: string x-go-type-skip-optional-pointer: true required: - name - accept DefinitionReference: description: > DefinitionReference defines where another resource references this Definition. type: object properties: type: type: string enum: - definition - action - trigger id: type: string format: ulid description: ID is the unique identifier of the Definition/Action/Trigger. x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid name: type: string description: > Name is unique identifier for the Definition/Action/Trigger within the scope of the Connector. It is expected to both human and machine-readable, i.e. "ProductFeature" or "stock_item". regex: ^[a-zA-Z0-9\-_]+$ required: - type - id - name securitySchemes: bearerToken: description: > Bearer token authentication used by the Versori Platform. External consumers must provide an API key, however internal consumers must provide a JWT id_token issued by our IdP. type: http scheme: bearer cookie: description: Cookie authentication used by the Versori Platform. type: apiKey in: cookie name: cookie ````