REST API — Naasher Documentation

API keys, OAuth, least-privilege scopes, endpoints, errors, and lifecycle rules for Naasher API v1.

Naasher's REST API is available on the Teams and Agency plans. Public SDK endpoints begin at https://api.naasher.com/api/sdk/v1; the interactive reference is available at api.naasher.com/docs, and the machine-readable contract is OpenAPI 3.1.

Authentication

Create an API key under Settings → Developers → API keys, then send it in either supported header:

curl https://api.naasher.com/api/sdk/v1/posts \
  -H "x-naasher-api-key: $NAASHER_API_KEY"

curl https://api.naasher.com/api/sdk/v1/posts \
  -H "Authorization: Bearer $NAASHER_API_KEY"

A key is shown once

Naasher stores the key fingerprint, not a retrievable plaintext copy. Put the value in a secret manager. If it is lost or exposed, create a replacement, update the controlled caller, and revoke the old key.

OAuth 2.1 for agents and third-party applications

Use Authorization Code with PKCE (S256) when an application acts for a user. Discovery starts at:

https://api.naasher.com/.well-known/oauth-authorization-server

Register through the published registration_endpoint, send resource=https://api.naasher.com/api/sdk/v1 in authorization and token requests, and request only required scopes. The user selects a workspace, and authorization remains bounded by that membership. Use refresh and revocation endpoints from discovery rather than sharing one long-lived key across customers.

Scopes

Scope	Capability
`channels:read`	Read connected accounts
`channels:update`	Manage channel-related destination presets
`posts:read`	Read posts
`posts:create`	Create a draft or post record
`posts:update`	Update an existing post record
`posts:schedule`	Schedule an existing post
`posts:publish`	Publish or retry a post through its provider
`posts:delete`	Delete a post record under the API contract
`posts:share`	Create, list, or revoke post share links
`media:read`	List media records
`media:upload`	Create an upload and confirm completion
`media:update`	Update media metadata
`media:delete`	Delete a media record
`schedule:read`	Read the calendar and schedule slots
`schedule:update`	Create, update, or delete schedule slots
`analytics:read`	Read available analytics
`webhooks:read`	Read webhook registrations
`webhooks:create`	Create a webhook registration
`webhooks:delete`	Delete a webhook registration
`*`	True wildcard: satisfies every scope check, including scopes added later

* is not shorthand for only the rows that existed when the key was created. The server treats it as a true wildcard and accepts every required permission. Avoid it unless the caller genuinely requires unrestricted API access. Start a new integration with read scopes, add each write scope separately, bind external actions to exact human authorization, and keep production and test credentials apart.

Endpoints

Posts

Method	Path	Purpose
`GET`	`/posts`	Cursor-paginated post list with filters
`POST`	`/posts`	Create a draft or scheduled post
`GET`	`/posts/:id`	Read one post
`POST`	`/posts/:id/schedule`	Schedule an existing post
`DELETE`	`/posts/:id`	Delete a post record

Example scheduled post:

curl -X POST https://api.naasher.com/api/sdk/v1/posts \
  -H "x-naasher-api-key: $NAASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "We shipped the new release today.",
    "channelIds": ["ch_123"],
    "scheduledAt": "2026-09-03T06:00:00.000Z"
  }'

Channels, analytics, and webhooks

Method	Path	Purpose
`GET`	`/channels`	List connected accounts
`GET`	`/channels/:id`	Read one connected account
`GET`	`/analytics`	Read the available analytics overview
`GET`	`/webhooks`	List webhook registrations
`POST`	`/webhooks`	Register a webhook
`DELETE`	`/webhooks/:id`	Delete a webhook registration

See Webhooks before accepting event-driven writes.

Rate limits and errors

Rate limiting applies per IP address and key. Read RateLimit-Policy, RateLimit, compatibility headers, and Retry-After rather than hard-coding a retry interval. Errors use a stable machine code inside a consistent envelope:

{ "error": { "code": "billing:feature_not_in_plan", "message": "API access is available on Teams and Agency." } }

Depend on code, not the human message. Do not automatically replay an uncertain create or schedule mutation until you have checked whether it already succeeded.

Versioning and deprecation

/api/sdk/v1 is the current stable major path. Compatible optional additions can land within v1; breaking changes require a new major version and an announced transition. Read API lifecycle for Deprecation, Sunset, and minimum transition rules.