Product UpdatesStatus PageAutomation Institute
English
Developer API
Resources

# Connector SDK

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.

# Quick reference

The Custom connectors resource contains the following endpoints:

Type Resource Description
GET /api/custom_connectors/search Search for custom connectors.
GET /api/custom_connectors/:id/code Fetches code for a custom connector.
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.
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

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

# Response

[
    {
        "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

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

# Response

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

# Custom connector developer APIs

Refer to the following sections for available custom connector operations. The following limits apply to custom connector developer APIs:

  • Custom connector code supports a maximum of 10MB of data
  • Custom connector API endpoints have a rate limit of 1 per second
  • Custom connector code must be UTF-8 and JSON compatible

# 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

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

{
    "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

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

# Sample response

{
  "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

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

{
    "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

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

{
    "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

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

# Sample response


{
    "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

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

Semantic example

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

Logical example

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

# Share custom connector

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

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

# Sample response

{
    "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

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

Logical: Latest release version is already shared example

{ "errors" => [{ "code" => 400, "title" => "The latest version of the custom connector is already shared" }] }
← Create a connection
Custom OAuth profiles →


Last updated: 4/2/2024, 11:42:24 PM

On this page