Automations_get

GET

/automations/{id}

const url = 'http://localhost:3000/api/automations/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/api/automations/example \
  --header 'Authorization: Bearer <token>'

Get a resource by ID

Authorizations

BearerAuth

Parameters

Path Parameters

required

A primary key, written as a decimal string so JavaScript never rounds it. The format makes the Go servers parse it into an int64: a malformed id is refused as a 400 before a handler runs. The pattern says the same in the contract, so a client (or a fuzzer) can tell a malformed id from a valid one without trying it. Eighteen digits is the most a key reaches, so every id the schema admits fits an int64.

string format: int64

/^[0-9]{1,18}$/

Unique identifier

Responses

200

The request has succeeded.

application/json

An Automation: an event-triggered, ordered sequence of steps. Created automations are always draft; activating is a separate, send-class operation.

object

required

Unique identifier

string format: int64

/^[0-9]{1,18}$/

name

required

Automation name

string

status

required

Lifecycle status

string

Allowed values: draft active

triggerEvent

required

Event action that enrolls a contact (e.g. “contact.created”, “email.opened”)

string

steps

required

The automation’s ordered, linear steps

Array<object>

One node in an automation’s ordered, linear sequence. A flat shape: email steps carry subject/body, wait steps carry seconds, tag steps carry the tag name.

object

type

required

Step kind

string

Allowed values: email wait apply_tag remove_tag http

subject

Email subject (email steps)

string

body

Email body as HTML (email steps), or the Liquid JSON request body (HTTP steps: Contact bindings only, strings JSON-escaped, up to 64 KiB, must render to valid JSON)

string

doc

The editor’s JSON document an email step’s body was built from, an opaque object checked by the server against the schema email_schema returns. Write it instead of body (both is a 422): the server renders the body from it in the same save, and a document that cannot be rendered refuses the whole save, naming the step. Writing only a body clears the step’s document.

object

key

additional properties

editorVersion

Version of the editor that rendered the document (email steps, read only)

string

seconds

Delay before the next step, in seconds (wait steps)

integer format: int32

tag

Tag name to apply to or remove from the enrolled contact (apply_tag and remove_tag steps)

string

Step id (HTTP steps). Assigned on save; send it back on edit so the step keeps its secrets.

string

url

Hook URL to POST to (HTTP steps). A secret: never returned. Omit it when editing to keep the stored URL. Up to 2 KiB, http or https.

string

headers

Up to 5 request headers (HTTP steps). On read, only the names are returned.

Array<object>

One request header of an HTTP step. The value is a secret: it is never returned.

object

name

required

Header name. Content-Type, Content-Length, Host and the webhook-* headers are set by sphericon.

string

value

Header value. Omit it when editing to keep the stored value of the header with this name.

string

secret

Signing secret (HTTP steps): when set, the request is signed with Standard Webhooks. Never returned. Omit it when editing to keep the stored secret.

string

clearSecret

Remove the signing secret on save (HTTP steps)

boolean

hasSecret

Whether a signing secret is stored (HTTP steps, read only)

boolean

archivedAt

When the automation was archived; null while it is kept

string format: date-time

createdAt

required

Creation timestamp

string format: date-time

updatedAt

required

Last update timestamp

string format: date-time

Example

{
  "status": "draft",
  "steps": [
    {
      "type": "email"
    }
  ]
}

400

RFC 7807 bad request response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

401

RFC 7807 unauthorized response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

404

RFC 7807 not found response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

429

RFC 7807 too many requests response: a rate limit was exceeded (ADR 0025)

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

Headers

Retry-After

required

integer format: int32

Seconds to wait before retrying

X-RateLimit-Limit

required

integer format: int32

The request budget of the window that was exceeded

X-RateLimit-Remaining

required

integer format: int32

Requests left in the current window

X-RateLimit-Reset

required

integer format: int64

Unix time at which the window resets