Skip to main content
Version: 1.0.0

Public API

Smackdab Public API.

Use Smackdab from an AI assistant​

You do not need to write API requests yourself. Connect Claude or another MCP-compatible AI client to the Smackdab MCP Server to search, create, update, and delete Smackdab data using plain-language instructions.

Use x-api-key for authentication. Branch and organization context are derived from the API key and should not be sent in request bodies.

Public list endpoints use bounded pagination. Unless an endpoint states otherwise, limit must be between 10 and 100.

Cursor-based list endpoints return items in ascending id order and use last_record_id as the next-page cursor input. Notes and documents also support created_since and updated_since ISO date-time filters for incremental sync.

Activities are available as a first-class v1 resource through /api/v1/activities... endpoints and through the activities sync resource.

When a write or user-list request supports delegated user attribution, send one of id_user, acting_user_id, or delegated_user_id. owner_id remains a resource ownership field and is not the same as the acting user.

Public API access is plan-gated. Free and Kickstarter plans cannot use the public API. Pro allows 100 read requests per second and 25 write requests per second. Unlimited allows 500 read requests per second and 125 write requests per second.

Public API responses include live rate-limit headers: X-RateLimit-Plan, X-RateLimit-Bucket, X-RateLimit-Limit, X-RateLimit-Limit-Read, X-RateLimit-Limit-Write, X-RateLimit-Remaining, and X-RateLimit-Reset. When the limit is exceeded, the API returns HTTP 429 with Retry-After.

Versioned /api/v1/... paths are the preferred stable contract. Existing unversioned public paths remain compatible aliases during the v1 rollout.

Public API errors may use the legacy { data, message, responseType } shape or the v1-compatible { error, status_code, request_id, responseType } envelope. Clients should read error.code when present and fall back to message for legacy responses.

Full rebuild for entity records and notes​

  1. Call POST /api/v1/entities/search with include_fields: "true" to discover the entity and its public fields.
  2. Page POST /api/v1/entity-records/search for that entity until data.pagination.has_more is false.
  3. Page POST /api/v1/notes/search once for the same entity, not once per record, and join notes locally by entity_record_id.

Incremental notes and entity-record sync​

Call GET /api/v1/sync/changes with an explicit limit (up to 100), updated_since, and resources=notes,entity_records. Keep updated_since and resources unchanged while following every next_cursor. Hydrate entity-record upserts through GET /api/v1/entity-records/{id}. Deduplicate by (resource, id, updated_at, operation) and advance the customer-owned checkpoint only after the complete cursor chain succeeds. Delete events keep data: null; use top-level entity_id and entity_record_id relationship fields.

Entity-record changes are row-level signals, not field-level history, and bulk retimestamps can be noisy. Keep periodic full rebuilds. Note search returns current attachment references, but attachment-only changes are not a separate sync event.

Authentication​

API Key is a simple and secure authentication method for public APIs. Clients include the key in API requests to verify access, using headers to send the key.

Security Scheme Type:

apiKey

Header parameter name:

x-api-key