API Reference

The Context Spine API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

https://api.contextspine.com/v1

Bearer Token Auth

Authentication

The Context Spine API uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

POST

Create Event

/v1/events

Create a new event in your workspace. Events are immutable and represent something that happened at a specific point in time.

Request Body

Parameter	Type	Required	Description
event_type	string	Required	Type of event (e.g., "user.created")
event_time	ISO 8601	Required	When the event occurred
source	string	Required	Source system identifier
payload	object	Optional	Event-specific data
entity_refs	array	Optional	References to entities involved
idempotency_key	string	Optional	Prevents duplicate event creation

Example Request

curl -X POST https://api.contextspine.com/v1/events \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "github.pull_request.merged",
    "event_time": "2024-01-15T10:30:00Z",
    "source": "github",
    "payload": {
      "pr_number": 42,
      "title": "Add new feature",
      "author": "jane_dev",
      "repository": "acme/api"
    },
    "entity_refs": [
      { "entity_type": "person", "external_id": "jane_dev" },
      { "entity_type": "repository", "external_id": "acme/api" }
    ]
  }'

Response

{
  "id": "evt_abc123xyz",
  "workspace_id": "ws_xyz789",
  "event_type": "github.pull_request.merged",
  "event_time": "2024-01-15T10:30:00Z",
  "record_time": "2024-01-15T10:30:05.123Z",
  "source": "github",
  "authority": "source_of_truth",
  "value_class": "hot",
  "payload": {
    "pr_number": 42,
    "title": "Add new feature",
    "author": "jane_dev",
    "repository": "acme/api"
  },
  "entity_refs": [
    { "entity_type": "person", "external_id": "jane_dev" },
    { "entity_type": "repository", "external_id": "acme/api" }
  ],
  "created_at": "2024-01-15T10:30:05.123Z"
}

Rate Limits

API requests are rate limited based on your plan:

Plan	Requests/min	Events/month
Starter	60	100,000
Pro	300	1,000,000
Enterprise	Custom	Unlimited

Errors

Context Spine uses conventional HTTP response codes:

200OKRequest succeeded

201CreatedResource created

400Bad RequestInvalid parameters

401UnauthorizedInvalid or missing API key

403ForbiddenInsufficient permissions

404Not FoundResource doesn't exist

429Rate LimitedToo many requests

500Server ErrorSomething went wrong