Skip to content
Swingback, home

API reference

Traits

Traits are typed attributes of end users and companies: string, number, boolean or date. The first value sent for a new key defines its type, and later values must have that type. To give a trait the type date, define it before sending its values.

The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

List traits#

GET/v1/workspaces/{workspace_id}/traits

Any API key: Read or Read and write

Returns the trait definitions, sorted by subject, then key, in a single page: a workspace has at most 50 per subject.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

Query parameters

  • subjectstring

    Only the traits of end users, or only those of companies. Both by default.

    One ofend_usercompany

Responses

Example

Request
curl "$SWINGBACK_API/traits?subject=end_user" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "data": [
    {
      "id": "trait_01h455vb4pex5vsknk084sn02q",
      "key": "plan",
      "subject": "end_user",
      "type": "string",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Define a trait#

POST/v1/workspaces/{workspace_id}/traits

An API key with Read and write access

Defines a key before any value is sent for it. This is how a trait gets the type date. A key that's already defined returns 409 trait_defined: to change its type, delete the trait first.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

Headers

  • Idempotency-Keystring

    Makes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.

    1 to 255 characters

Request body

application/jsonrequired
  • keystringrequired

    The trait's key, a letter followed by up to 63 letters, digits or underscores.

  • subjectstringrequired

    What the trait describes: end_user for end users, company for companies.

    One ofend_usercompany
  • typestringrequired

    The type of the trait's values. A date takes 2026-09-28 or an RFC 3339 time.

    One ofstringnumberbooleandate

Responses

Example

Request
curl -X POST "$SWINGBACK_API/traits" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "company",
    "key": "renewal_date",
    "type": "date"
  }'
Response · 201 Created
{
  "id": "trait_01h455vb4pex5vsknk084sn02q",
  "key": "renewal_date",
  "subject": "company",
  "type": "date",
  "created_at": "2026-09-28T14:03:12.482Z"
}

Delete a trait#

DELETE/v1/workspaces/{workspace_id}/traits/{trait_id}

An API key with Read and write access

Deletes the trait's definition and every value of it.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • trait_idstringrequired

    The trait's id.

    Starts with trait_

Responses

  • 204
    No ContentThe trait and its values were deleted.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/traits/trait_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

The trait definition object#

Fields

  • idstring

    Starts with trait_

  • keystring

    The trait's key, a letter followed by up to 63 letters, digits or underscores.

  • subjectstring

    What the trait describes: end_user for end users, company for companies.

    One ofend_usercompany
  • typestring

    The type of the trait's values. A date takes 2026-09-28 or an RFC 3339 time.

    One ofstringnumberbooleandate
  • created_atstring · date-time

Example

The trait definition object
{
  "id": "trait_01h455vb4pex5vsknk084sn02q",
  "key": "plan",
  "subject": "end_user",
  "type": "string",
  "created_at": "2026-09-28T14:03:12.482Z"
}

Search pages, sections and code: a setting, an event, a method.