Status Page API — SharedStatus Developer Documentation

Quick Start

Create a page, save the API Token, share the public URL, then add or update items as progress changes.

Create Page (Optional initial items)

POST /v1/status-pages

Optionally include an items array to create initial workflow steps in the same request. Each item can optionally include state and sortOrder. When supplied, item IDs are returned in the create response.

Save API Token

Save the apiToken returned in the response.

Share Public URL

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

Update Items as Progress Changes

Use the API Token to update item states or add new steps later.

Authorization: Bearer YOUR_API_TOKEN

Customer Sees Updates

Customers view progress using the publicUrl.

Try it in 30 Seconds

Create a page using POST /v1/status-pages (optionally with initial items)
Note the item id values returned in the create response (when initial items are supplied)
Copy the publicUrl and open it in a browser
Use the apiToken to update an item using its id
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 T3jO7d3pCecYTJSXKFDtr8mSJDn8tuMaBCNYnXBjBx0" \
  -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 T3jO7d3pCecYTJSXKFDtr8mSJDn8tuMaBCNYnXBjBx0" \
  -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 the page-specific API Token (apiToken) to add, update, or remove items.

Current API model

Anonymous page creation
API Token authentication
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

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 the page-specific API Token:
```
Authorization: Bearer {apiToken}
```

Keep the API Token private. Anyone with this token can modify that page's items. Only a hash of the token is stored server-side.

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

When you create a page, you receive three different credentials:

Public URL

Used by customers and viewers. Safe to share.

publicUrl

Admin URL

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

adminUrl

API Token

Used by API integrations in the Authorization header. Keep private.

apiToken

Endpoints

POST /v1/status-pages

Create a new status page. Returns URLs, a one-time API Token (apiToken), 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.

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 API Token. 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 YOUR_API_TOKEN" \
  -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 API Token. 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 YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"state\":1}"

DELETE /v1/status-pages/{publicCode}/items/{itemGuid}

Delete an item. Requires API Token. 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 YOUR_API_TOKEN"

Typical flow

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

Create a status page using POST /v1/status-pages — empty or with optional initial items
Save the API Token securely — it is only returned at creation (or when regenerated via the web admin)
Add items if the page was created empty — optionally with state and sortOrder — or update existing items as work progresses
Share the publicUrl with customers or viewers
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 still returns its own apiToken
Use the page apiToken for later item updates — not the integration key
Integration keys are for trusted, higher-volume integrations
Keys can be revoked if abused

Need a higher create limit or want to integrate SharedStatus into your software? Send feedback or email support@sharedstatus.com.

Limits

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

Future development

The current API is intentionally simple: each page has its own API Token, and no developer account is required. API Tokens are page-specific, not global credentials.

Planned improvements include:

Developer accounts
Managed API credentials
Token generation and regeneration from the web admin
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

Have an idea or need something for your integration? Send feedback.

Project Status Page API

Quick Start

Try it in 30 Seconds

Complete Working Example

C# example

Item States

Item IDs

Use cases

Overview

Current API model

Base URL

Authentication

Public URL

Admin URL

API Token

Endpoints

Typical flow

Bulk integrations

Limits

Future development