Skip to content
SphericonSphericon docs

Integrations_get

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

Get a resource by ID

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
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

Section titled “Responses”

200

Section titled “200”

The request has succeeded.

Media typeapplication/json

A sending-provider Integration. Credentials are write-only: the config is returned with secrets redacted.

object
id
required

Unique identifier

string format: int64
/^[0-9]{1,18}$/
name
required

Human-readable label

string
channel
required

Delivery channel

string
Allowed values: email sms
provider
required

Concrete provider

string
Allowed values: smtp ses
enabled
required

Whether this integration may be used for sending

boolean
isDefault
required

Whether this is the default provider for its channel

boolean
maxPerSecond
required

Send rate limit set on the Integration: most messages per second; null means none

integer format: int32
nullable
maxPerDay
required

Send rate limit set on the Integration: most messages per rolling 24 hours; null means none

integer format: int32
nullable
sendLimit
required

The Send rate limit as enforced and 24-hour usage

object
perSecond
required

Most messages per second

object
limit
required

The ceiling in messages; null means this window is not limited

integer format: int32
nullable
source
required

Where the ceiling comes from; null when there is none

string
Allowed values: manual provider
perDay
required

Most messages per rolling 24 hours

object
limit
required

The ceiling in messages; null means this window is not limited

integer format: int32
nullable
source
required

Where the ceiling comes from; null when there is none

string
Allowed values: manual provider
sentLast24h
required

Messages the provider accepted from this Integration in the last 24 hours

integer format: int32
warnings
required

Reasons to review the limit; empty when there is nothing to flag

Array<string>
Allowed values: unlimited providerQuotaUnavailable
config
required

Provider config (secrets redacted)

object
One of:

SMTP config without the password

object
kind
required
string
Allowed values: smtp
host
required
string
port
required
integer format: int32
username
string
nullable
from
required
string format: email
<= 320 characters
fromName
string
nullable
preset
required

The Preset this Integration’s provider callbacks are read with; null when it receives none

string
nullable
params
required

The Preset’s params as saved. A secret param (writeOnly in the Preset’s schema) is shown as ********, never its value

object
key
additional properties
secretsRetiring
required

Names of the secret params that are rotating: a retiring value is still accepted beside the current one

Array<string>
hookUrl
required

Where the provider posts this Integration’s callbacks: paste it into the provider. The key in it is an address, not the authentication (the Preset’s signature or secret is)

string
createdAt
required

Creation timestamp

string format: date-time
updatedAt
required

Last update timestamp

string format: date-time

Example 

{
  "channel": "email",
  "provider": "smtp",
  "sendLimit": {
    "perSecond": {
      "source": "manual"
    },
    "perDay": {
      "source": "manual"
    },
    "warnings": [
      "unlimited"
    ]
  },
  "config": {
    "kind": "smtp"
  }
}

400

Section titled “400”

RFC 7807 bad request response

Media typeapplication/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

Section titled “401”

RFC 7807 unauthorized response

Media typeapplication/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

Section titled “404”

RFC 7807 not found response

Media typeapplication/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

Section titled “429”

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

Media typeapplication/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

Section titled “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