canonical: https://jentic.com/apis/publishwith.ai/publishwith

# publishwith.ai API

The publishwith.ai API publishes AI-generated reports and dashboards as governed HTML artifacts inside your workspace and controls who can see them. A static artifact is uploaded as HTML or Markdown files, while a dynamic one is rendered server-side from a YAML manifest and Liquid templates. You can then search artifacts, fetch their source for editing, and share them with a tenant user, group, audience, or external email at view, edit, or own access. A generic action endpoint exposes the complete action set, including SQL execution and access management.

## For AI agents

Publish an HTML or Markdown report as a governed artifact, update it by name, search and list artifacts, and share one with a person, group, or external email at view, edit, or own access. A generic action call reaches the rest of the action set.

## Scope

Does not handle report generation from raw prompts, public website hosting on your own domain, or email delivery campaigns. Use for publishing, finding, and sharing governed reports and dashboards in a publishwith.ai workspace only.

## Capabilities

- Publish a static artifact from index.html or index.md files, or a dynamic one from a YAML manifest and Liquid templates
- Republish an artifact by name, resolving a VERSION_CHANGED conflict with the confirmation_token from the 409 response
- Full-text search and list artifacts in your tenant, and fetch an artifact's raw source files by version
- Share an artifact with a tenant user, group, audience, or external email at view, edit, or own access, with an expiring link for external recipients
- Resolve a colleague by name or email in your organization directory before sharing
- Attach binary files to an artifact through a short-lived upload token
- Invoke any other action, such as execute_sql, set_visibility, or revoke_access, through the generic call endpoint

## Use cases

### Agent-published reports

An AI agent that writes an analysis can publish it straight to publishwith.ai as an index.md file, which the service renders to a styled page, and then share the result with the person who asked for it. Because publish is idempotent by the name-derived slug, the agent re-running the same report updates the page rather than creating a duplicate, and a 409 VERSION_CHANGED response protects a newer edit by someone else.

Example prompt: Publish an artifact named 'Weekly Churn Report' in static mode with files containing index.md, then share it with principal priya@example.com at view access

### Data-backed dynamic dashboards

Teams that want a dashboard to stay current publish in dynamic mode: a YAML manifest defines the data and Liquid templates render it server-side. The generic call endpoint also exposes actions such as list_tables and execute_sql, so an agent can inspect the available data before writing the manifest.

Example prompt: Call the action list_tables through the generic call endpoint, then publish an artifact named 'Pipeline Dashboard' with mode dynamic, a manifest, and templates

### Controlled sharing with outside reviewers

When a report must go to a client, the share operation grants one principal at a time. Internal users open the canonical in-app URL, while an external email receives a tokenized, expiring link capped at view access, so reviewers outside the tenant can read a report but cannot edit or own it. Sharing never changes the artifact's document-wide visibility.

Example prompt: Share the artifact with slug q3-board-pack with external email client@example.org at view access with ttl_days 7

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/publish` | Publish or update an artifact |
| GET | `/api/v1/artifacts` | List artifacts in your tenant |
| GET | `/api/v1/search` | Full-text search across artifacts |
| GET | `/api/v1/artifacts/{slug}/source` | Get an artifact's source files |
| POST | `/api/v1/artifacts/{slug}/share` | Share an artifact with a principal |
| GET | `/api/v1/people` | Resolve a person in your directory |
| POST | `/api/v1/call` | Invoke any publishwith.ai action |

## Key resources

- **Artifacts** — Governed HTML reports and dashboards, published in static or dynamic mode
- **Artifact source** — Raw files of an artifact version for editing and republishing
- **Shares** — Access grants to users, groups, audiences, or external emails
- **People** — Organization directory entries resolved by name or email
- **Uploads** — Token-based binary file attachments for an artifact
- **Actions** — The full publishwith.ai action set behind the generic call endpoint

## 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:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 52 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 74 / 100
- **View full report:** https://jentic.com/apis/publishwith.ai/publishwith/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 publishwith.ai by hand means creating a personal API key for its Bearer auth, handling 409 VERSION_CHANGED retries with a confirmation token, and choosing between typed endpoints and the generic action call. Through Jentic you install once, import publishwith.ai from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The typed publishwith.ai operations put the artifact slug in the URL path (`/api/v1/artifacts/{slug}/...`), so a rule can pin your agent to one artifact for source reads and sharing. The generic `/api/v1/call` endpoint carries its action in the request body, so allowing it allows every action; you choose the operations the agent may call, and that endpoint is not included unless you add it.
- **Credential handling:** Your publishwith.ai API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish a report as a web page' or 'share a dashboard with a colleague', and Jentic returns the matching publishwith.ai operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Notion API** — Notion stores reports as pages and databases in a shared workspace.
- **Gamma API** — Gamma generates presentation-style documents and decks from a prompt.
- **Netlify API** — Netlify deploys static sites to a public host.

## FAQ

### What authentication does the publishwith.ai API use?

The publishwith.ai API authenticates with a Bearer token in the Authorization header, using a personal API key generated from Connect, per its OpenAPI spec. Enterprise workspaces may restrict or disable key creation. The file upload operation is the exception: it is authenticated by the upload token in its path and needs no Bearer header. Through Jentic the API key is stored once and injected at call time, so it never appears in your agent's prompt or logs.

### What is the difference between static and dynamic publishing in publishwith.ai?

Static mode uploads files, with index.html as HTML or index.md as Markdown that is auto-rendered to a styled page. Dynamic mode supplies a YAML manifest and Liquid templates that the service renders server-side. Both go through POST `/api/v1/publish` and are idempotent by the slug derived from the artifact name.

### What are the rate limits for the publishwith.ai API?

The OpenAPI spec does not specify rate limits for the publishwith.ai API. Check https://publishwith.ai for current limits on your workspace.

### How do I publish a report with the publishwith.ai API through Jentic?

Search Jentic for 'publish a report as a web page', which returns POST `/api/v1/publish` with its input schema, then send a name and files with an index.md or index.html. If it returns 409 VERSION_CHANGED, re-send with the confirmation_token to overwrite deliberately. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a publishwith.ai MCP server?

You don't need an MCP server to give your agent the publishwith.ai API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it, discovering the publish, search, and share operations by intent rather than holding their tool definitions in context.

### Can I limit what my agent is allowed to do with the publishwith.ai API?

Yes. Write a rule that allows only POST `/api/v1/publish`, GET `/api/v1/search`, and GET `/api/v1/artifacts`, so the agent can publish and find reports but cannot share them or reach actions like delete_artifact, and every call it makes is logged. Leave POST `/api/v1/call` out of the rule, since that one endpoint carries every action in its request body.