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.
Authenticate with an Auth personal access token
CRM-created developer tokens are deprecated. Use an Auth-issued personal access token (PAT) for new integrations and migrate existing integrations to PATs. Branch and organization context come from the token's workspace; do not send them in request bodies.
In Auth Hub, select the intended workspace, open API Keys, and choose Create API Key. Select Personal and the Smackdab CRM application, choose the required scopes (including crm:read for the first request below), and save the token in your client's secret store. Do not choose a Workspace or system token for this CRM flow.
For direct API requests, use https://api.smackdab.ai and send only Authorization: Bearer <personal-access-token> as your authentication credential. Remove the old x-api-key header and any CRM session credentials.
First request
Set SMACKDAB_PAT using your environment or secret manager, then run:
curl 'https://api.smackdab.ai/api/v1/users/me/positions' \
--header "Authorization: Bearer $SMACKDAB_PAT"
Use a Smackdab CRM personal access token as Authorization: Bearer <personal-access-token>. Tokens identify one Auth user and workspace and are subject to their CRM scopes, lifecycle, and current permissions. Do not put tokens in request bodies, URLs, logs, or prompts.
Normal personal-token requests resolve exactly one eligible CRM position. If the caller has one eligible position, the API selects it automatically. If the caller has multiple positions, first call GET /api/v1/users/me/positions, choose data.items[].uuid, and send it as X-Smackdab-Position-UUID on the normal request. The same choice may be taken from error.details.available_positions[].uuid after PUBLIC_POSITION_REQUIRED.
GET /api/v1/users/me/positions
Authorization: Bearer <personal-access-token>
GET /api/v1/quotes/143
Authorization: Bearer <personal-access-token>
X-Smackdab-Position-UUID: c778bba8-20aa-4c12-88b8-ac02f1531b40
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.
Personal-token requests cannot select an actor through id_user, acting_user_id, or delegated_user_id; including any of them returns 400 PUBLIC_ACTOR_OVERRIDE_NOT_ALLOWED. The actor and position come only from the validated token and optional position selector. owner_id remains resource ownership, not authentication identity.
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.
Personal-token scopes and lifecycle
The position-discovery endpoint requires crm:read. Each normal route also requires its documented CRM scope and applicable module and record permissions. Personal tokens can expire or be revoked, may be restricted by CIDR, and stop working when the owning user, workspace membership, or Smackdab CRM application access becomes inactive. A 401 personal-token response includes WWW-Authenticate: Bearer.
Legacy API-key migration
CRM-created developer tokens and their x-api-key authentication are deprecated. The legacy schema remains in this reference only to describe compatibility during migration; it is not the setup path for new integrations. No retirement date is specified here.
To migrate, create an Auth personal token for Smackdab CRM in the same workspace, replace x-api-key with Authorization: Bearer <personal-access-token>, remove id_user, acting_user_id, and delegated_user_id, and discover the user's positions as shown above. If needed, send X-Smackdab-Position-UUID. Verify the integration's required operations with the PAT before retiring its old credential.
Troubleshoot your first request
| Error code | Next step |
|---|---|
PUBLIC_CREDENTIAL_REQUIRED | Send the PAT in Authorization: Bearer, not x-api-key. |
PUBLIC_TOKEN_INACTIVE | Check expiry, revocation, and that the token is Personal and belongs to Smackdab CRM. |
PUBLIC_POSITION_REQUIRED | Choose an authorized position and send its UUID in X-Smackdab-Position-UUID. |
PUBLIC_POSITION_NOT_AVAILABLE | Ask your CRM administrator to assign an active position in this workspace. |
PUBLIC_PRINCIPAL_NOT_AUTHORIZED | Check the token owner's CRM access and selected workspace. |
PUBLIC_PERSONAL_TOKEN_REQUIRED | Confirm you are using a personal token; if so, ask support to check PAT enablement for the workspace. |
PUBLIC_AUTH_UNAVAILABLE | Retry later; if it persists, report the status and error code to support. |
When contacting support, include the URL, HTTP status, error code, and request ID if available. Never include the token.
Personal-token synchronization
Call GET /api/v1/sync/changes with a fixed updated_since value and optional fixed resource set. Personal-token pages return a signed opaque v1.* cursor; reuse it unchanged until data.pagination.has_more is false. If authorization changes between pages, the API returns HTTP 409 PUBLIC_SYNC_PERMISSION_CHANGED with error.details.restart_required: true. Restart from the last durable boundary instead of continuing that cursor.
Authentication
- HTTP: Bearer Auth
- API Key: LegacyApiKeyAuth
Smackdab CRM personal access token created in Auth Hub.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | PersonalAccessToken |
Deprecated legacy API key accepted only during the bounded migration period. New integrations must use BearerAuth.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | x-api-key |