Skip to content
FolioSign inStart your trial

API reference

Plans and status

The plan catalogue, the webhook event catalogue and service status.

GET/v1/public/legal

Read the current legal document versions#

The current version, effective date and link of the Terms, the Privacy Policy and the Data Processing Addendum. Show the links and send the versions you displayed when a person accepts them. Send If-None-Match with the last ETag to get a cheap 304.

Auth. None. This route is public.

Auth
No key
Operation id
publicLegal

Parameters

Parameters
NameInDescription
If-None-MatchheaderThe ETag of the copy you already hold. If it is current the answer is 304 with no body. (string)

Responses

200 Success. Read the current legal document versions.
200 example
{
  "status": true,
  "message": "legal",
  "data": {
    "object": "legal",
    "documents": [
      {
        "document": "terms",
        "version": "2026-10-25",
        "effective_iso": "2026-10-25",
        "effective_label": "25 October 2026",
        "url": "https://folio.candensa.com/terms"
      }
    ]
  }
}
400 The request could not be read.
400 example
{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
422 A field failed validation, or an Idempotency-Key was reused with a different body.
422 example
{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
500 Something went wrong. Quote error.request_id.
500 example
{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/public/legal"

GET/v1/public/plans

Read the plan catalogue#

The plan catalogue: plans, their prices by interval and currency, the allowances each carries, per-unit prices for usage beyond the allowance, and add-ons. Show prices from here instead of copying them, because plans change. Send If-None-Match with the last ETag to get a cheap 304.

Auth. None. This route is public.

Auth
No key
Operation id
publicPlans

Parameters

Parameters
NameInDescription
If-None-MatchheaderThe ETag of the copy you already hold. If it is current the answer is 304 with no body. (string)

Responses

200 Success. Read the plan catalogue.
200 example
{
  "status": true,
  "message": "plans",
  "data": {
    "trial_days": 14,
    "plans": [
      {
        "key": "starter",
        "name": "Starter",
        "prices": [
          {
            "interval": "month",
            "currency": "USD",
            "amount": 2900
          }
        ],
        "entitlements": [
          {
            "feature": "hours",
            "quota": 480
          }
        ],
        "meter_prices": [
          {
            "meter": "hours",
            "amount": 250
          }
        ]
      }
    ],
    "addons": []
  }
}
400 The request could not be read.
400 example
{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
422 A field failed validation, or an Idempotency-Key was reused with a different body.
422 example
{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
500 Something went wrong. Quote error.request_id.
500 example
{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/public/plans"

GET/v1/public/webhook-events

Read the webhook event catalogue without a key#

The same catalogue as GET /v1/webhook-event-types, readable without a key so documentation and tooling can show the current events. It lists no church data.

Auth. None. This route is public.

Auth
No key
Operation id
publicWebhookEvents

Responses

Response data fields
FieldTypeDescription
allstringSubscribe to this value to receive every event.
api_versionstringThe event schema version these definitions describe.
envelopeobject
exampleobjectA complete sample body.
schemaobjectJSON Schema 2020-12 of the body Folio POSTs to your endpoint.
groupsobject[]The groups of events.
schemasobjectShared object schemas that event schemas reference as #/schemas/<name>.
totalinteger (int64)The total number of items.
200 Success. Read the webhook event catalogue without a key.
200 example
{
  "status": true,
  "message": "webhook_event_catalogue",
  "data": {
    "groups": [
      {
        "key": "note",
        "label": "Notes",
        "events": [
          {
            "object": "webhook_event_type",
            "type": "note.published",
            "group": "note",
            "group_label": "Notes",
            "description": "A note was published to its share page.",
            "source": "notes",
            "fields": [
              {
                "name": "teaching_id",
                "type": "string",
                "required": true,
                "description": "The teaching this note belongs to."
              }
            ],
            "example": {
              "type": "note.published"
            }
          }
        ]
      }
    ],
    "total": 1,
    "all": "*"
  }
}
400 The request could not be read.
400 example
{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
422 A field failed validation, or an Idempotency-Key was reused with a different body.
422 example
{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
500 Something went wrong. Quote error.request_id.
500 example
{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/public/webhook-events"

GET/v1/status

Read the service status#

The public status of Folio's components and any open incident. status is operational, degraded or major_outage.

Auth. None. This route is public.

Auth
No key
Operation id
statusSurface

Responses

200 Success. Read the service status.
200 example
{
  "status": true,
  "message": "status",
  "data": {
    "object": "status",
    "status": "operational",
    "components": [
      {
        "key": "api",
        "name": "API",
        "group": "core",
        "status": "operational"
      }
    ],
    "incidents": []
  }
}
400 The request could not be read.
400 example
{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
422 A field failed validation, or an Idempotency-Key was reused with a different body.
422 example
{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}
500 Something went wrong. Quote error.request_id.
500 example
{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/status"

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.