Custom connectors

The following endpoints allow you to create and manage custom connectors, as well as generate a Workato Schema from sample JSON and CSV documents. These endpoints are also used in the SDK CLI tool for schema generation commands.

Rate limits

Custom connector resources have the following rate limits:

The following additional limitations apply to custom connector resources:

Quick reference

The Custom connectors resource contains the following endpoints:

Type	Resource	Description
POST	/api/sdk/generate_schema/json	Generates Workato schema from a stringified JSON sample.
POST	/api/sdk/generate_schema/csv	Generates Workato schema from a stringified CSV sample.
GET	/api/custom_connectors/search	Search for custom connectors.
GET	/api/custom_connectors/:id/code	Fetches code for a custom connector.
POST	/api/custom_connectors	Creates a custom connector.
POST	/api/custom_connectors/:id/release	Releases the latest version of a custom connector.
POST	/api/custom_connectors/:id/share	Shares a custom connector.
PUT	/api/custom_connectors/:id	Updates a custom connector.

Generate schema from JSON

Generates Workato schema from a stringified JSON sample.

POST /api/sdk/generate_schema/json

URL parameters

Name	Type	Description
sample	string optional	Stringified JSON of the sample document to parse.

Sample request

shell

curl  -X POST https://www.workato.com/api/sdk/generate_schema/json \
      -H 'Authorization: Bearer <api_token>' \
      --data-raw '{
     "sample": "{ \"test\":\"hello\"}"
     }'

Response

json

[
    {
        "control_type": "text",
        "label": "Test",
        "type": "string",
        "name": "test"
    }
]

Generate schema from CSV

Generates Workato schema from a stringified CSV sample.

POST /api/sdk/generate_schema/csv

URL parameters

Name	Type	Description
sample	string optional	Stringified CSV of the sample document to parse.
col_sep	string optional	Column delimiter for the CSV sample. Must be one of `comma`, `semicolon`, `space`, `tab`, `colon`, `pipe`.

Sample request

shell

curl  -X POST https://www.workato.com/api/sdk/generate_schema/csv \
      -H 'Authorization: Bearer <api_token>' \
      --data-raw '{
     "sample": "first_name,5\nhello,world",
     "col_sep": "comma"
     }'

Response

json

[
    {
        "control_type": "text",
        "label": "First name",
        "type": "string",
        "name": "first_name"
    },
    {
        "control_type": "text",
        "label": "Last name",
        "type": "string",
        "name": "last_name"
    }
]

Search custom connector

The Search operation allows you to search for a custom connector in your workspace by title.

LIMITED TO TEN MOST RECENT RELEASES

Only the ten most recently released versions are returned.

GET /api/custom_connectors/search

Payload

Name	Type	Description
title	String required	The case-sensitive title of the custom connector for which you plan to search. The search returns partial matches.

Sample request

shell

curl -X GET https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors/search \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "<connector_title>"
  }'

Sample response

json

{
    "id": 3066,
    "name": "new_connector_1_connector_4771_1626869114",
    "title": "Acme Connector",
    "logo": "<base_64 encoded logo>",
    "latest_version": 6,
    "latest_version_note": "Latest version",
    "latest_released_version": 4,
    "latest_released_version_note": null,
    "latest_shared_version": 6,
    "latest_shared_version_note": "Latest version",
    "oem_shared_version": 2,
    "oem_shared_at": "2024-02-02T08:05:22.047-07:00",
    "released_versions": [
        {
            "version": 4,
            "version_note": null,
            "created_at": "2022-08-11T07:24:58.890-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        },
        {
            "version": 2,
            "version_note": "hello world",
            "created_at": "2024-02-08T05:05:34.136-07:00",
            "released_at": "2024-02-08T21:33:41.713-07:00"
        }
    ]
},

Get custom connector code

The Get custom connector code operation allows you to fetch a custom connector's code.

GET /api/custom_connectors/:id/code

URL parameters

Name	Type	Description
ID	Integer required	The ID of the custom connector for which you plan to fetch the code. You can find your custom connector ID in the search custom connector endpoint.

Sample request

shell

curl -X GET https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors/1/code \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>"

Sample response

json

{
  "data": {
    "code": "<connector_code_stringified>"
  }
}

Create custom connector

The Create operation allows you to create a custom connector in your workspace.

POST /api/custom_connectors

Payload

Name	Type	Description
title	String	The title of the custom connector you plan to create.
logo	String	The logo you plan to add to your custom connector. Your logo must be encoded in Base64 format.
description	String	A description of your custom connector. Your description is visible when you share your custom connector through a private link or through the community library. Markdown is allowed.
note	String	Notes for the initial version of your custom connector.
code	String	The Ruby code for your custom connector. Ensure that the code is stringified. Your code cannot exceed 10MB in size.

Sample request

shell

curl -X POST https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "<connector_title>",
    "logo": "<connector_logo_base_64>",
    "description": "<connector_description>",
    "note": "<connector_note>",
    "code": "<connector_code>"
  }'

Sample response

json

{
    "id": 3066,
    "name": "new_connector_1_connector_4771_1626869114",
    "title": "Acme Connector",
    "logo": "<base_64 encoded logo>",
    "latest_version": 6,
    "latest_version_note": "Latest version",
    "latest_released_version": 4,
    "latest_released_version_note": null,
    "latest_shared_version": 6,
    "latest_shared_version_note": "Latest version",
    "oem_shared_version": 2,
    "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
    "released_versions": [
        {
            "version": 4,
            "version_note": null,
            "created_at": "2022-08-11T07:24:58.890-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        },
        {
            "version": 2,
            "version_note": "hello",
            "created_at": "2021-07-21T05:05:34.136-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        }
    ]
}

Update custom connector

The Update operation allows you to update a custom connector in your workspace.

PUT /api/custom_connectors/:id

URL parameters

Name	Type	Description
ID	Integer required	The ID of the custom connector you plan to update. You can find your custom connector ID in the search custom connector endpoint.

Sample request

shell

curl -X PUT https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors/:id \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "<connector_title>",
    "logo": "<connector_logo_base_64>",
    "description": "<connector_description>",
    "note": "<connector_note>",
    "code": "<connector_code>"
  }'

Sample response

json

{
    "id": 3066,
    "name": "new_connector_1_connector_4771_1626869114",
    "title": "Acme Connector",
    "logo": "<base_64 encoded logo>",
    "latest_version": 6,
    "latest_version_note": "Latest version",
    "latest_released_version": 4,
    "latest_released_version_note": null,
    "latest_shared_version": 6,
    "latest_shared_version_note": "Latest version",
    "oem_shared_version": 2,
    "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
    "released_versions": [
        {
            "version": 4,
            "version_note": null,
            "created_at": "2022-08-11T07:24:58.890-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        },
        {
            "version": 2,
            "version_note": "hello",
            "created_at": "2021-07-21T05:05:34.136-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        }
    ]
}

Release custom connector

The Release operation allows you to release the latest version of your custom connector. After you release the new version, it is used in all future jobs.

POST /api/custom_connectors/:id/release

URL parameters

Name	Type	Description
ID	Integer required	The ID of the custom connector you plan to release. You can find your custom connector ID in the search custom connector endpoint.

Sample request

shell

curl -X POST https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors/:id/release \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>"

Sample response

json


{
    "id": 3066,
    "name": "new_connector_1_connector_4771_1626869114",
    "title": "Acme Connector",
    "logo": "<base_64 encoded logo>",
    "latest_version": 6,
    "latest_version_note": "Latest version",
    "latest_released_version": 4,
    "latest_released_version_note": null,
    "latest_shared_version": 6,
    "latest_shared_version_note": "Latest version",
    "oem_shared_version": 2,
    "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
    "released_versions": [
        {
            "version": 4,
            "version_note": null,
            "created_at": "2022-08-11T07:24:58.890-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        },
        {
            "version": 2,
            "version_note": "hello",
            "created_at": "2021-07-21T05:05:34.136-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        }
    ]
}

HTTP response codes

Name	Description	Sample reply
`200`	Success	`{"message": "Connector released successfully"}`
`400`	Bad request	`{"message": "Fix code errors before releasing the connector"}` or `{"message": "Connector’s released version is already the latest version"}`

400 error examples

Syntax example

json

{ "errors" => [{ "code" => 400, "title" => "Line 2 has syntax errors. Please check Workato UI for further details." }] }

Semantic example

json

{ "errors" => [{ "code" => 400, "title" => "Expected string or lambda for 'description' in 'test_trigger' trigger but got Symbol." }] }

Logical example

json

{ "errors" => [{ "code" => 400, "title" => "The latest version of the custom connector is already released." }] }

The Share operation allows you to share the most recently released version of your custom connector. After you share your custom connector, all workspaces that have installed your connector through a private link or from the community library receive an update notification.

POST /api/custom_connectors/:id/share

URL parameters

Name	Type	Description
ID	Integer required	The ID of the custom connector you plan to share. You can find your custom connector ID in the search custom connector endpoint.

Sample request

shell

curl -X POST https://<DC-SPECIFIC-API-BASE-URL>/api/custom_connectors/:id/share \
  -H "Authorization: Bearer <API-CLIENT-TOKEN>"

Sample response

json

{
    "id": 3066,
    "name": "new_connector_1_connector_4771_1626869114",
    "title": "Acme Connector",
    "logo": "<base_64 encoded logo>",
    "latest_version": 6,
    "latest_version_note": "Latest version",
    "latest_released_version": 4,
    "latest_released_version_note": null,
    "latest_shared_version": 6,
    "latest_shared_version_note": "Latest version",
    "oem_shared_version": 2,
    "oem_shared_at": "2022-08-08T08:05:22.047-07:00",
    "released_versions": [
        {
            "version": 4,
            "version_note": null,
            "created_at": "2022-08-11T07:24:58.890-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        },
        {
            "version": 2,
            "version_note": "hello",
            "created_at": "2021-07-21T05:05:34.136-07:00",
            "released_at": "2021-09-26T21:33:41.713-07:00"
        }
    ]
}

HTTP response codes

Name	Description	Sample reply
`200`	Success	`{"message": "Connector shared successfully"}`
`400`	Bad request	`{"message": "There is no released version to share"}` or `{"message": "Connector’s shared version is already the latest released version"}`

400 error examples

Logical: No released version to share example

json

{ "errors" => [{ "code" => 400, "title" => "Release the latest version of the code first" }] }

Logical: Latest release version is already shared example

json

{ "errors" => [{ "code" => 400, "title" => "The latest version of the custom connector is already shared" }] }

Last updated:

Custom connectors ​

Rate limits ​

Quick reference ​

Generate schema from JSON ​

URL parameters ​

Sample request ​

Response ​

Generate schema from CSV ​

URL parameters ​

Sample request ​

Response ​

Search custom connector ​

Payload ​

Sample request ​

Sample response ​

Get custom connector code ​

URL parameters ​

Sample request ​

Sample response ​

Create custom connector ​

Payload ​

Sample request ​

Sample response ​

Update custom connector ​

URL parameters ​

Sample request ​

Sample response ​

Release custom connector ​

URL parameters ​

Sample request ​

Sample response ​

HTTP response codes ​

400 error examples ​

Share custom connector ​

URL parameters ​

Sample request ​

Sample response ​

HTTP response codes ​

400 error examples ​

Custom connectors

Rate limits

Quick reference

Generate schema from JSON

URL parameters

Sample request

Response

Generate schema from CSV

URL parameters

Sample request

Response

Search custom connector

Payload

Sample request

Sample response

Get custom connector code

URL parameters

Sample request

Sample response

Create custom connector

Payload

Sample request

Sample response

Update custom connector

URL parameters

Sample request

Sample response

Release custom connector

URL parameters

Sample request

Sample response

HTTP response codes

400 error examples

Share custom connector

URL parameters

Sample request

Sample response

HTTP response codes

400 error examples