API Overview

Overview

The Nashra API is REST over JSON. Use it to manage your audience, sync custom fields, build segments, fetch posts, and connect Nashra to the rest of your stack.

Base URL

https://app.nashra.ai/api/v1

All authenticated endpoints sit under this base. The public endpoints that power your site (no key needed) are namespaced under /api/v1/tenants/{slug}/... — see Public website API below.

Authentication

Authenticated endpoints need an API key, sent as a Bearer token:

Authorization: Bearer your_api_key_here

Create keys in Settings → API keys. See Authentication for the full steps.

What you can do

Subscribers

• List, search, and filter subscribers by status (subscribed, unsubscribed, unconfirmed)
• Create and update subscribers, including tags and custom field values
• Delete subscribers, by UUID or email address
• Bulk-upsert up to 100 subscribers per request

Subscribers you create through the API are added as subscribed right away — double opt-in doesn't apply. When you update a subscriber, a tags array replaces their whole tag list; the bulk endpoint merges tags instead.

Tags

• List, create, update, and delete tags

A tag's color is one of eight names: cyan, orange, yellow, green, blue, purple, pink, or red. Hex values are rejected. Leave color out and Nashra picks one from the tag's name.

Custom fields

• List, create, update, and delete custom fields (text, number, date, boolean)

A field's data_name uses lowercase letters, digits, and underscores. The keys email, first_name, last_name, phone, phone_country, and visitor_id are reserved, so you can't use them.

Segments

• List segments
• Get segment details with subscriber counts
• Create new segments programmatically

Segments support create, list, and get only — there's no update or delete endpoint yet. Manage existing segments from Audience in the dashboard.

Posts

• List posts that are live on the web, newest first — filter with since to get only posts updated after a timestamp
• Fetch a single post by UUID

Both include unlisted posts, and the response doesn't say which posts are unlisted. Posts are read-only through the API — there's no create or update endpoint. Write and publish posts from the Nashra editor.

Public website API

A second, unauthenticated namespace at /api/v1/tenants/{slug}/... powers your public site. {slug} is your subdomain (the yourname in yourname.nashra.website) or your verified custom domain. Use it to build a custom front end on top of your Nashra content:

• GET /tenants/{slug} — Workspace info: name, logo, fonts, social links, tracking code
• GET /tenants/{slug}/posts — Published posts, filterable by category (unlisted posts are left out)
• GET /tenants/{slug}/posts/{slug} — A single post, including unlisted ones
• GET /tenants/{slug}/resolve/{path} — The landing page or post at a top-level path
• GET /tenants/{slug}/bio — Your Hub: profile, links, sections, subscribe form
• GET /tenants/{slug}/search-index — Everything readers can search on your Hub
• POST /tenants/{slug}/subscribe — Subscribe to your list
• POST /tenants/{slug}/contact — Send a message through your Hub's contact form
• GET/POST /tenants/{slug}/magic-links/{identifier} — A Resource's form, and submitting it (the path keeps the Resources' old name)
• GET /tenants/{slug}/sitemap.xml and /robots.txt — SEO files

One public endpoint sits outside /v1: the form action URL, POST https://app.nashra.ai/api/subscribe/{identifier}, that every HTML form in Settings → Forms posts to. See Embeds & Form Actions.

The endpoints that take submissions, and the ones a page polls, are rate-limited per visitor — see Rate Limits.

Response format

All responses are JSON. Successful responses wrap the result in data, sometimes with a message:

{
  "data": { ... },
  "meta": {
    "version": "v1",
    "timestamp": "2026-05-05T10:30:00+00:00"
  }
}

Errors

Errors come in four shapes, depending on what went wrong:

Here's a 404 from deleting a subscriber that doesn't exist:

{
  "error": {
    "message": "Subscriber not found.",
    "code": "NOT_FOUND"
  },
  "meta": { "version": "v1", "timestamp": "..." }
}

And a 422 from a bad email address:

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Pagination

The subscribers, tags, custom fields, and posts lists accept per_page (default 15, max 100) and page. Responses don't include totals or a page count — keep requesting the next page until you get back fewer than per_page items. The segments list isn't paginated.

Rate limits

Authenticated requests share a limit of 60 per minute per key. Public form submissions have their own, stricter limits. See Rate Limits.

Versioning

The API is versioned in the URL (/api/v1). Breaking changes ship under a new version; non-breaking additions (new fields, new endpoints) are made within v1.

What's next