API documentation

Project Status Page API

Use the SharedStatus API to create status pages and keep customer progress updates in sync from your own software. Create a free account, generate an API key on the Developers page, and use it to authenticate requests for pages in your account.

Quick Start

Create an account, generate an API key, create or claim status pages, then update items as progress changes.

Create an account

Sign in or create a free account with your email — no password required.

Create an API key

Open the Developers page and create your account API key (ss_acct_…). Save it securely — it is only shown once.

Create a page (Optional initial items)
POST /v1/status-pages

Create pages via the API or the website, then save them to your account from the page editor. Optionally include an items array to create initial workflow steps in the same request.

Share public URL

Share the publicUrl with your customer once items are on the page.

Update items as progress changes

Use your account API key on pages owned by your account:

Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY
Customer sees updates

Customers view progress using the publicUrl.

Try it in 30 Seconds

  1. Create an account and generate an API key on the Developers page
  2. Create a page using POST /v1/status-pages (optionally with initial items) and save it to your account
  3. Note the item id values returned in the create response (when initial items are supplied)
  4. Copy the publicUrl and open it in a browser
  5. Use your account API key to update an item using its id
  6. Refresh the public page and see the change instantly

This is the fastest way to see how SharedStatus works before building a full integration.

Complete Working Example

This example uses option 2 — creating a page with initial items. You can also create an empty page and add items using POST /v1/status-pages/{publicCode}/items.

Create page (with optional initial items)

curl -X POST "https://api.sharedstatus.com/v1/status-pages" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Kitchen renovation\",\"items\":[{\"text\":\"Survey booked\",\"state\":2,\"sortOrder\":0},{\"text\":\"Materials ordered\",\"state\":1,\"sortOrder\":1},{\"text\":\"Work scheduled\",\"state\":0,\"sortOrder\":2}]}"

Create response

{
  "publicCode": "z4hiCKGpsFUg",
  "adminCode": "4XLI4LN9su",
  "apiToken": "T3jO7d3pCecYTJSXKFDtr8mSJDn8tuMaBCNYnXBjBx0",
  "publicUrl": "https://sharedstatus.com/s/z4hiCKGpsFUg",
  "adminUrl": "https://sharedstatus.com/a/4XLI4LN9su",
  "items": [
    {
      "id": "8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1",
      "text": "Survey booked",
      "sortOrder": 0,
      "state": 2,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    },
    {
      "id": "3f4a5b6c-7d8e-49f0-a1b2-c3d4e5f60718",
      "text": "Materials ordered",
      "sortOrder": 1,
      "state": 1,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    },
    {
      "id": "9a8b7c6d-5e4f-43a2-b1c0-d9e8f7a6b504",
      "text": "Work scheduled",
      "sortOrder": 2,
      "state": 0,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    }
  ]
}

Update an existing item

curl -X PATCH "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg/items/3f4a5b6c-7d8e-49f0-a1b2-c3d4e5f60718" \
  -H "Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"state\":1}"

Add an additional item later

curl -X POST "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg/items" \
  -H "Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"Final inspection booked\",\"state\":0,\"sortOrder\":3}"

Add item response

{
  "id": "5d2d9a7b-5f2a-46f5-bf73-6db4dc8c74a9",
  "text": "Final inspection booked",
  "sortOrder": 3,
  "state": 0,
  "createdUtc": "2026-06-08T15:20:00Z",
  "updatedUtc": "2026-06-08T15:20:00Z"
}

state and sortOrder are optional when creating items. If omitted, state defaults to Pending and sortOrder is assigned automatically. Responses include the final saved state and sortOrder. Item IDs are returned when items are created — during page creation and when adding items later — so no follow-up GET is needed. Share the publicUrl with your customer once items are on the page.

C# example

Create a page and read the response using HttpClient. The request items array is optional; the response always includes items with generated IDs when initial items were supplied. 

var response = await httpClient.PostAsJsonAsync(
    "https://api.sharedstatus.com/v1/status-pages",
    new
    {
        title = "Kitchen renovation",
        items = new[] // optional
        {
            new { text = "Survey booked", state = 2, sortOrder = 0 },
            new { text = "Materials ordered", state = 1, sortOrder = 1 },
            new { text = "Work scheduled", state = 0, sortOrder = 2 }
        }
    });

response.EnsureSuccessStatusCode();

var page =
    await response.Content.ReadFromJsonAsync<CreatePageResponse>();

Response type

public sealed record CreatePageResponse(
    string PublicCode,
    string AdminCode,
    string ApiToken,
    string PublicUrl,
    string AdminUrl,
    IReadOnlyList<StatusItemResponse> Items);

public sealed record StatusItemResponse(
    Guid Id,
    string Text,
    int SortOrder,
    int State,
    DateTime CreatedUtc,
    DateTime UpdatedUtc);

Item States

0 = Pending
1 = Active
2 = Complete

Item responses include a numeric state field. Use these values when creating or updating items.

state and sortOrder are optional when creating items. If omitted, state defaults to Pending and sortOrder is assigned automatically.

Item IDs

When items are created — during page creation or via POST .../items — SharedStatus returns a unique item id (a GUID). When initial items are supplied in the create request, their IDs are included in the create response.

Store these values if you plan to update or delete items later.

Use the returned id in PATCH and DELETE requests. Item IDs are stable public identifiers — you never need internal database keys.

Use cases

  • Push project status updates from a CRM, job management tool, or internal dashboard
  • Give customers a live progress tracking page without building your own status UI
  • Automate customer updates when milestones change in your workflow
  • Embed shareable project progress links generated by your application

Overview

The SharedStatus status API lets you build integrations that create live project status pages and keep their checklist items up to date. Viewers use the publicUrl; your integration uses an account API key from the Developers page for pages owned by your account.

Current API model

  • Free SharedStatus accounts with passwordless sign-in
  • Account API keys for authenticated requests
  • Anonymous page creation for quick tests (legacy page apiToken still returned)
  • JSON request and response bodies
  • Pages can be created empty or with initial items

Base URL

https://api.sharedstatus.com

All endpoints are versioned under /v1.

Authentication

Create a free account and generate an API key on the Developers page. Use it in the Authorization header for item create, update, and delete requests on pages owned by your account: 

Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY

Each endpoint falls into one of three access levels:

  • Anonymous — POST /v1/status-pages. No Authorization header required.
  • Public — GET /v1/status-pages/{publicCode}. No auth required. Anyone with the publicCode or publicUrl can read the page.
  • Authenticated — item create, update, and delete endpoints. Requires either:
    • Your account API key (ss_acct_…) for pages saved to your account — recommended
    • A legacy page API token (apiToken) returned when a page is created anonymously via the API

Keep API keys and tokens private. Anyone with them can modify the associated page items. Only a hash of each credential is stored server-side.

Integration keys (see Bulk integrations) are separate from account API keys. They only apply to page creation and cannot update items.

When you create a page, you receive URLs for sharing and management:

Public URL

Used by customers and viewers. Safe to share.

publicUrl

Admin URL

Used to manage the page in the browser. Keep private.

adminUrl

Account API key

Created on the Developers page. Use in the Authorization header for owned pages.

ss_acct_…

Endpoints

POST /v1/status-pages

Create a new status page. Returns URLs, a legacy one-time page token (apiToken) for anonymous integrations, and an items array. When initial items are supplied, their generated IDs are returned in the create response. If no items were supplied, items is an empty array. Save pages to your account and use an account API key for ongoing access.

Option 1 — empty page

{
  "title": "Kitchen renovation"
}

Add items later using POST /v1/status-pages/{publicCode}/items.

Option 2 — page with optional initial items

{
  "title": "Kitchen renovation",
  "items": [
    { "text": "Survey booked", "state": 2, "sortOrder": 0 },
    { "text": "Materials ordered", "state": 1, "sortOrder": 1 },
    { "text": "Work scheduled", "state": 0, "sortOrder": 2 }
  ]
}

state and sortOrder are optional on each item. If omitted, state defaults to Pending and sortOrder follows the item's position in the array. The response returns the final saved state and sortOrder.

Response 201 Created (with initial items)

{
  "publicCode": "z4hiCKGpsFUg",
  "adminCode": "4XLI4LN9su",
  "apiToken": "T3jO7d3pCecYTJSXKFDtr8mSJDn8tuMaBCNYnXBjBx0",
  "publicUrl": "https://sharedstatus.com/s/z4hiCKGpsFUg",
  "adminUrl": "https://sharedstatus.com/a/4XLI4LN9su",
  "items": [
    {
      "id": "8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1",
      "text": "Survey booked",
      "sortOrder": 0,
      "state": 2,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    },
    {
      "id": "3f4a5b6c-7d8e-49f0-a1b2-c3d4e5f60718",
      "text": "Materials ordered",
      "sortOrder": 1,
      "state": 1,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    }
  ]
}

Response 201 Created (empty page)

{
  "publicCode": "z4hiCKGpsFUg",
  "adminCode": "4XLI4LN9su",
  "apiToken": "T3jO7d3pCecYTJSXKFDtr8mSJDn8tuMaBCNYnXBjBx0",
  "publicUrl": "https://sharedstatus.com/s/z4hiCKGpsFUg",
  "adminUrl": "https://sharedstatus.com/a/4XLI4LN9su",
  "items": []
}

curl (empty page)

curl -X POST "https://api.sharedstatus.com/v1/status-pages" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Kitchen renovation\"}"

curl (with optional initial items)

curl -X POST "https://api.sharedstatus.com/v1/status-pages" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Kitchen renovation\",\"items\":[{\"text\":\"Survey booked\"},{\"text\":\"Materials ordered\"}]}"
GET /v1/status-pages/{publicCode}

Fetch a status page and its items. Public — no auth required. Item id values are also returned when items are created (page create or POST .../items) — a GET is not required solely to discover IDs. See Item States for state values.

Response 200 OK (page with items)

{
  "publicCode": "z4hiCKGpsFUg",
  "title": "Kitchen renovation",
  "latestUpdate": null,
  "createdUtc": "2026-06-08T14:30:00Z",
  "updatedUtc": "2026-06-08T14:30:00Z",
  "expiresUtc": null,
  "items": [
    {
      "id": "8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1",
      "text": "Survey booked",
      "sortOrder": 0,
      "state": 0,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T14:30:00Z"
    },
    {
      "id": "3f4a5b6c-7d8e-49f0-a1b2-c3d4e5f60718",
      "text": "Materials ordered",
      "sortOrder": 1,
      "state": 1,
      "createdUtc": "2026-06-08T14:30:00Z",
      "updatedUtc": "2026-06-08T15:10:00Z"
    }
  ]
}

Response 200 OK (empty page)

{
  "publicCode": "z4hiCKGpsFUg",
  "title": "Kitchen renovation",
  "latestUpdate": null,
  "createdUtc": "2026-06-08T14:30:00Z",
  "updatedUtc": "2026-06-08T14:30:00Z",
  "expiresUtc": null,
  "items": []
}

curl

curl "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg"
POST /v1/status-pages/{publicCode}/items

Add a checklist item. Requires authentication (account API key or legacy page apiToken). state and sortOrder are optional. If omitted, state defaults to Pending and the item is added to the end of the list. The response includes the item id and the final saved state and sortOrder. See Item IDs and Item States.

Request body

{
  "text": "Final inspection booked",
  "state": 0,
  "sortOrder": 3
}

Response 201 Created

{
  "id": "5d2d9a7b-5f2a-46f5-bf73-6db4dc8c74a9",
  "text": "Final inspection booked",
  "sortOrder": 3,
  "state": 0,
  "createdUtc": "2026-06-08T15:20:00Z",
  "updatedUtc": "2026-06-08T15:20:00Z"
}

curl

curl -X POST "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg/items" \
  -H "Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"Final inspection booked\",\"state\":0,\"sortOrder\":3}"
PATCH /v1/status-pages/{publicCode}/items/{itemGuid}

Update an item's text and/or state. Requires authentication. Send at least one field. Use the id returned when the item was created. See Item IDs and Item States.

Request body

{
  "text": "Work in progress",
  "state": 1
}

Response 200 OK

{
  "id": "8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1",
  "text": "Work in progress",
  "sortOrder": 1,
  "state": 1,
  "createdUtc": "2026-06-08T14:30:00Z",
  "updatedUtc": "2026-06-08T15:25:00Z"
}

curl

curl -X PATCH "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg/items/8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1" \
  -H "Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"state\":1}"
DELETE /v1/status-pages/{publicCode}/items/{itemGuid}

Delete an item. Requires authentication. Use the id returned when the item was created.

Response 204 No Content

curl

curl -X DELETE "https://api.sharedstatus.com/v1/status-pages/z4hiCKGpsFUg/items/8c83d648-6f1d-4d69-8f1c-98eb3c8ef8a1" \
  -H "Authorization: Bearer ss_acct_YOUR_ACCOUNT_API_KEY"

Typical flow

After the Quick Start steps above, a typical integration follows this pattern:

  1. Create an account and generate an API key on the Developers page
  2. Create status pages using POST /v1/status-pages — empty or with optional initial items — and save them to your account
  3. Store your account API key securely — manage, regenerate, or revoke it from the Developers page
  4. Add items if the page was created empty — optionally with state and sortOrder — or update existing items as work progresses
  5. Share the publicUrl with customers or viewers
  6. Store each item id from the create or add-item response for later updates and deletes

Bulk integrations

Anonymous page creation is rate limited to protect the service. If your system needs to create many status pages — for example one page per customer during a batch import or customer email run — use an integration key on create requests.

Send the key on create requests using:

SharedStatus-Integration-Key: YOUR_INTEGRATION_KEY

Example

curl -X POST "https://api.sharedstatus.com/v1/status-pages" \
  -H "SharedStatus-Integration-Key: YOUR_INTEGRATION_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Kitchen renovation\"}"
  • Integration keys are only used when creating pages via POST /v1/status-pages
  • Each created page may still return a legacy page apiToken for that page only
  • Use your account API key for item updates on owned pages — not the integration key
  • Integration keys are for trusted, higher-volume integrations
  • Keys can be revoked if abused

Limits

  • Anonymous create requests are rate limited per IP (15 per hour)
  • Integration key create requests have higher per-key limits (issued individually)
  • Authenticated item changes are rate limited per credential (60 per minute)
  • Anonymous and free pages may expire
  • Abuse may be blocked

Future development

Account API keys are managed from the Developers page after you sign in. Pages saved to your account can be updated using your account key today.

Planned improvements include:

  • Creating pages directly under your account via the API
  • Webhooks for status and item changes
  • QR code generation for public status pages
  • More automation and integration options
  • Improvements based on user and developer feedback
An unhandled error has occurred. Reload 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.