Getting started

The Stoneity Public API lets you read and write tickets, boards, users and knowledge base articles in your workspace, and receive webhooks when something changes.

1. Create an API key

1. Sign in to Stoneity as an administrator.
2. Open Settings → Apps → API keys and click New key.
3. Give the key a name, pick the role it should act with, tick the scopes it needs and optionally an expiry.
4. Copy the key. It starts with stoneity_ and is shown only once.

Every key acts as a dedicated service account: tickets it creates, comments it adds and state changes it makes are attributed to that account in the ticket history, notifications and reports. The role you pick decides which boards and records the key can see, exactly like a human user with that role.

2. Call the API

Base URL:

Environment	Base URL
Production	https://api.stoneity.com/public/v1
Test	https://api.test.stoneity.com/public/v1

Send the key as a bearer token. No other header is required — the key identifies your workspace.

curl https://api.stoneity.com/public/v1/me \
  -H "Authorization: Bearer stoneity_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "apiKey": { "id": 12, "name": "Zapier", "prefix": "stoneity_ab12cd34", "scopes": ["tickets:read", "tickets:write"] },
  "serviceUser": { "id": 418, "userName": "apikey-ab12cd34", "fullName": "Zapier API", "roleId": 1 },
  "workspace": { "domain": "https://acme.stoneity.com", "name": "Acme" },
  "limits": { "requestsPerMinute": 120, "maxWebhookSubscriptions": 10 }
}

3. Create your first ticket

Boards, their fields and states are discoverable through GET /boards and GET /boards/{id}. Use the field ids from there:

curl -X POST https://api.stoneity.com/public/v1/tickets \
  -H "Authorization: Bearer $STONEITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10042-created" \
  -d '{
    "boardId": "65fef78fa23b4d12ab34cd56",
    "subject": "VPN access issue",
    "description": "Cannot connect since this morning.",
    "requesterEmail": "jane@example.com",
    "priority": "High",
    "fields": [{ "fieldId": "SOURCE_SYSTEM_...", "value": "Shop" }]
  }'

The response is the ticket representation used everywhere in the API and in webhook payloads. Tickets created through the API carry "channel": "api".

4. Get notified

Register a webhook under Settings → Apps → Webhooks (or POST /webhooks) to receive events such as ticket.created or ticket.state_changed. See Webhooks and Verifying signatures.

Next steps

• Authentication & scopes
• Rate limits & idempotency
• API reference