Examples in

Transforms API

The REST API behind Transforms: create pipelines and read them; save and list their versions; test a document, run a saved pipeline on a request, and list the templates to start from; manage credential slots; and check your plan and usage. Every operation below shows its request in the language picked at the top of the page. Transforms has no SDK yet, so TypeScript, Python and Go use each language's usual HTTP client.

Calls take an API key for Transforms, created in your account console. The quickstart walks through a first pipeline, and the reference covers the objects, roles, each plan's limits and the errors.

Base URL: https://transforms.nimbusnexus.net
Authentication: Authorization: Bearer <API key>
Version: Transforms 0.1.1 · OpenAPI spec

Before the examples

The examples read your API key from TRANSFORMS_API_KEY.

Shell

export TRANSFORMS_API_KEY="<your-api-key>"

Pipelines

GET/v1/pipelines

List Pipelines

The workspace's pipelines, newest first, each without its document (GET by id has it).

Parameters

Name	In	Type	Description
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/pipelines" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

POST/v1/pipelines

Create Pipeline

Create a pipeline and its version 1, checked whole: a 422 invalid_pipeline names the first problem's step, path and reason. Every plan. A document whose auth step names a slot needs an owner or admin (403 role).

Request body

Field	Type	Description
name	string	—
pipeline*	object	—

Responses

201Successful Response
401error.code = unauthorized
402error.code = quota_exceeded | workspace_frozen | workspace_suspended
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X POST "https://transforms.nimbusnexus.net/v1/pipelines" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paid invoices",
    "pipeline": {
      "version": 1,
      "steps": [
        {
          "filter": {
            "type": "invoice.paid",
            "data": {
              "amount": {
                "$gte": 100000
              }
            }
          },
          "note": "Paid invoices of $1,000 or more"
        },
        {
          "drop": [
            "data.customer.email",
            "**.phone"
          ]
        },
        {
          "set": {
            "event_type": "{{ type }}",
            "amount_display": "{{ data.amount | money(data.currency) }}"
          }
        },
        {
          "headers": {
            "set": {
              "X-Event-Type": "{{ type }}"
            }
          }
        }
      ]
    }
  }'

GET/v1/pipelines/templates

List Pipeline Templates

transform-core's gallery (RFC-0030): the ready-made pipelines one starts from. Slack, Discord and Microsoft Teams messages, and the body with only the fields listed or without its personal data. They come from the engine version this service runs, so a template never names a step or a filter it could not run. The same for every workspace; saving one makes a copy that is the workspace's own.

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/pipelines/templates" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

POST/v1/pipelines/test

Test Pipeline

Run a document once on a request and save nothing: the editor's Test. It is checked as a save checks it (422 invalid_pipeline), and shares the run rate. What its auth steps add shows masked (Bearer ••••). A drop or a failure is a 200 saying so, because that is the answer a test exists to give.

Request body

Field	Type	Description
body	object	—
headers	object	—
meta	object	—
pipeline*	object	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X POST "https://transforms.nimbusnexus.net/v1/pipelines/test" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "version": 1,
      "steps": [
        {
          "filter": {
            "type": "invoice.paid",
            "data": {
              "amount": {
                "$gte": 100000
              }
            }
          },
          "note": "Paid invoices of $1,000 or more"
        },
        {
          "drop": [
            "data.customer.email",
            "**.phone"
          ]
        },
        {
          "set": {
            "event_type": "{{ type }}",
            "amount_display": "{{ data.amount | money(data.currency) }}"
          }
        },
        {
          "headers": {
            "set": {
              "X-Event-Type": "{{ type }}"
            }
          }
        }
      ]
    },
    "body": {
      "type": "invoice.paid",
      "data": {
        "id": "in_42",
        "amount": 150000,
        "currency": "usd",
        "customer": {
          "name": "Ana Silva",
          "email": "[email protected]",
          "phone": "+1 202 555 0142"
        }
      }
    }
  }'

GET/v1/pipelines/{pipeline_id}

Read Pipeline

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

PATCH/v1/pipelines/{pipeline_id}

Patch Pipeline

Rename it, switch it on or off, or save new content as its next version. disabled stops it running, here and at every consumer. Saving a document whose auth step names a slot needs an owner or admin (403 role for a member); the same content again, and a document without one, do not. Such a new version also needs confirm_destinations to name every service that runs it by reference: otherwise it is a 409 destinations_unconfirmed listing them, and nothing is saved.

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—

Request body

Field	Type	Description
name	string \| null	—
pipeline	object \| null	—
status	"enabled" \| "disabled" \| null	—
confirm_destinations	array of string \| null	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_frozen | workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X PATCH "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE/v1/pipelines/{pipeline_id}

Delete Pipeline

Delete a pipeline and its versions, for good. An owner or admin. A consumer still running it then fails each delivery, so confirm_destinations must name every service that does: otherwise it is a 409 destinations_unconfirmed listing them.

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—
confirm_destinations	query	array of string	Every service that runs it by reference, as a read lists them.

Responses

204Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X DELETE "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

POST/v1/pipelines/{pipeline_id}/run

Run Pipeline

Run a saved pipeline on a request: whatever the caller sends as body, headers and meta. Stateless: nothing about the request is kept, and the run is only counted. The current version runs unless version names a kept one. The answer says what the pipeline did: ok with what to send, dropped by a filter, or failed. Each is a 200; retrying a failed gets the same answer. What an auth step adds is masked (Bearer ••••): to send with a credential, run the pipeline by reference from the product that sends. Past the plan's rate, or with too many of the workspace's runs under way at once, a 429. Open while a charge is unsettled.

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—

Request body

Field	Type	Description
body	object	—
headers	object	—
meta	object	—
version	integer \| null	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X POST "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>/run" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "type": "invoice.paid",
      "data": {
        "id": "in_42",
        "amount": 150000,
        "currency": "usd"
      }
    }
  }'

GET/v1/pipelines/{pipeline_id}/versions

List Pipeline Versions

The kept versions, newest first, each without its document (GET one version has it).

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>/versions" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

GET/v1/pipelines/{pipeline_id}/versions/{version}

Read Pipeline Version

Parameters

Name	In	Type	Description
pipeline_id*	path	string	—
version*	path	integer	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/pipelines/<pipeline_id>/versions/<version>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

Credential slots

GET/v1/slots

List Slots

The workspace's slots, newest first.

Parameters

Name	In	Type	Description
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/slots" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

POST/v1/slots

Create Slot

Add a place for a credential: a pipeline's auth step names it by the id this answers. It holds no value. A product that runs the pipeline by reference binds it to a secret of its own.

Request body

Field	Type	Description
label	string	—

Responses

201Successful Response
401error.code = unauthorized
402error.code = quota_exceeded | workspace_frozen | workspace_suspended
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X POST "https://transforms.nimbusnexus.net/v1/slots" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/v1/slots/{slot_id}

Read Slot

Parameters

Name	In	Type	Description
slot_id*	path	string	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/slots/<slot_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

PATCH/v1/slots/{slot_id}

Patch Slot

Change a slot's label.

Parameters

Name	In	Type	Description
slot_id*	path	string	—

Request body

Field	Type	Description
label	string \| null	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_frozen | workspace_suspended
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X PATCH "https://transforms.nimbusnexus.net/v1/slots/<slot_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE/v1/slots/{slot_id}

Delete Slot

Delete a slot, for good. Refused (409 slot_in_use) while a pipeline's current version names it: change those pipelines first.

Parameters

Name	In	Type	Description
slot_id*	path	string	—

Responses

204Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X DELETE "https://transforms.nimbusnexus.net/v1/slots/<slot_id>" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

Plan and usage

GET/v1/plan

Read Plan

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/plan" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

GET/v1/usage

Read Usage

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
413error.code = payload_too_large
422error.code = validation_error
500error.code = internal_error

Example

curl -X GET "https://transforms.nimbusnexus.net/v1/usage" \
  -H "Authorization: Bearer $TRANSFORMS_API_KEY"

Edit this page on GitHub