canonical: https://jentic.com/apis/newt/newt

# Newt API

Newt is a headless content management platform that exposes four API surfaces from a single Bearer-secured spec - the CDN API for read-only delivery, the Content API for app metadata, the Assets API for media files, and the Form API for form submissions. The five endpoints cover listing and fetching content items, reading app definitions, retrieving asset binaries by name, and submitting form payloads. Each surface lives on a per-space subdomain ({spaceUid}.cdn.newt.so, .api.newt.so, .assets.newt.so, .form.newt.so) so requests are isolated per tenant.

## For AI agents

Read content, retrieve assets, and submit forms on the Newt headless CMS platform. Single Bearer token spans CDN, content, assets, and form delivery surfaces.

## Scope

Does not handle content creation, content updates, asset uploads, or form definition management - use for content read, asset download, and form submission only.

## Capabilities

- Fetch a paginated list of content items from a Newt model with filter and sort query parameters
- Retrieve a single content item by ID for detail-page rendering
- Read app metadata including model definitions through GET `/space/apps/{appUid}`
- Download asset files from the {spaceUid}.assets.newt.so subdomain by asset UID and name
- Submit form responses via POST /{formUid} on the {spaceUid}.form.newt.so subdomain
- Authenticate every surface with the same Bearer token issued from the Newt dashboard

## Use cases

### Headless Site Content Delivery

Marketing teams running a Newt-backed site call GET /{appUid}/{modelUid} for list pages and GET /{appUid}/{modelUid}/{contentId} for detail pages. Combined with GET `/space/apps/{appUid}` to fetch model definitions at build time, this is enough to render a full content-driven website. The CDN subdomain delivers responses from the edge so live pages stay responsive.

Example prompt: Fetch all published items from the 'blog' model in the 'marketing' app and render a paginated index page

### Asset Pipeline for Marketing Pages

Pages that include images or PDFs hosted in Newt fetch them from the {spaceUid}.assets.newt.so subdomain via GET /{assetUid}/{assetName}. The asset server returns the binary directly so the marketing site can stream files without a separate CDN configuration. Pairing the asset endpoint with the content endpoints gives a single CMS pipeline for both copy and media.

Example prompt: Download the asset 'hero-banner.jpg' with assetUid img_2026 from the marketing space

### Form Submission for Lead Capture

Marketing landing pages route form submissions to Newt by POSTing to {formUid} on the {spaceUid}.form.newt.so subdomain. Newt stores the response alongside the form definition so the marketing team reviews leads in the same dashboard as content. Adding this endpoint to a static site removes the need for a separate forms-as-a-service vendor.

Example prompt: Submit a contact form with formUid contact-form, name 'Sam', email 'sam@example.com', and message 'demo request'

### Agent-Driven CMS Operations

An AI agent uses the Newt API through Jentic to operate across content, assets, and forms in one workflow. The agent might enumerate models in an app, fetch a specific content item, and download its hero image - all on the same Bearer token. Jentic abstracts the four subdomains so the agent treats Newt as one logical API.

Example prompt: For every published blog post, fetch the post content and download its associated hero asset into a manifest

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/{appUid}/{modelUid}` | List content items in a model with filter and sort |
| GET | `/{appUid}/{modelUid}/{contentId}` | Fetch a single content item by ID |
| GET | `/space/apps/{appUid}` | Get app metadata and model definitions |
| GET | `/{assetUid}/{assetName}` | Download an asset file from the assets subdomain |
| POST | `/{formUid}` | Submit form data to the form subdomain |

## Key resources

- **Contents** — Read content items in a model - list with filters or fetch by single content ID
- **Apps** — Read app metadata including model definitions
- **Assets** — Download asset binaries by UID and filename from the assets subdomain
- **Forms** — Submit form responses to the form subdomain by formUid

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 70 / 100
- **View full report:** https://jentic.com/apis/newt/newt/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Newt by hand means learning its bearer token auth and picking the right one of four per-space hosts for content, assets, and form submission (cdn, API, assets, and form subdomains). Through Jentic you install once, import the Newt API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Newt puts the app id in the URL path (/{appUid}/{modelUid}), so a rule can pin your agent to one app: it can read that app's content and download its assets. You choose the operations it may call, so form submission is not included unless you add it.
- **Credential handling:** Your Newt bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch content', 'download an asset', or 'submit a form', and Jentic returns the matching Newt operation with its input schema and the correct host base so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Newt CDN API** — The newt.so spec covers only the three CDN delivery endpoints, without assets or forms
- **Contentful API** — Contentful is a larger global headless CMS with delivery, management, and asset APIs
- **Storyblok API** — Storyblok bundles a headless CMS with a visual editor and similar delivery endpoints

## FAQ

### What authentication does the Newt API use?

Newt uses a Bearer token issued from the Newt dashboard. The same token authenticates the CDN, content, assets, and form endpoints, so an agent only holds one credential. Through Jentic the token is stored in the encrypted vault and injected into the Authorization header automatically.

### Can I download an image from Newt with this API?

Yes. GET /{assetUid}/{assetName} on the {spaceUid}.assets.newt.so host returns the asset binary. Combined with the content endpoints, this lets a single agent fetch both the article and its associated hero image in one workflow.

### What are the four subdomains in the Newt API?

Newt splits the API across four host subdomains under the {spaceUid} tenant: cdn.newt.so for read content, api.newt.so for content metadata, assets.newt.so for asset files, and form.newt.so for form submissions. Through Jentic the host is selected automatically based on which operation is loaded.

### How do I submit a form to Newt through Jentic?

Search Jentic for 'submit a form to newt', load the POST /{formUid} schema, and execute with the formUid and the response payload. Jentic resolves the {spaceUid}.form.newt.so host and injects the Bearer token, so the agent only supplies the form fields.

### Can the Newt API create or update content items?

The five endpoints in this spec cover read-only content delivery, asset downloads, and form submission. Creating, updating, or deleting content items is handled through the editing API surface, which is not part of this spec.

### Can I limit what my agent is allowed to do with the Newt API?

Yes. Because you run Jentic One yourself, your own rules decide which Newt operations and credentials the agent may use. Newt puts the app id in the URL path (GET /{appUid}/{modelUid}), so a rule can pin the agent to a single app so it only reads that app's content and downloads its assets. You also choose the operations it may call, so form submission via POST /{formUid} is excluded unless you add it.