Agent publishing

Publish files and pages from agents.

Publr gives agents a small, revocable API surface for turning generated HTML or another UTF-8 artifact into a live sandbox URL. It uses the same moderation, ownership, and analytics model as the browser upload flow for PDFs, images, ZIPs, and webpages.

Create token OpenAPI Markdown

Browse docs

Getting Started

Overview Quickstart Authentication

Publish

CLI Direct API Responses

Reference

Endpoints Schemas Errors Discovery Limits

Overview

What agents can do

The first public agent surface is intentionally narrow: create and revoke tokens from an authenticated user session, verify an agent token, and publish one inline UTF-8 file through the same security pipeline used by browser uploads.

Inline file per publish request

Agent scopes: publish and token management

Default page size for token listings

Quickstart

Ship the first URL

1

Create a token

Sign in to Publr and create an agent token from the account token screen. Copy the raw token once and store it in your agent or local shell.

Set environment variables

export PUBLR_API_URL=https://api.publr.host
export PUBLR_API_TOKEN=pk_live_...

Publish with the CLI

npx @publr/cli whoami

npx @publr/cli publish ./index.html \
  --slug agent-demo \
  --name "Agent demo" \
  --content-type text/html \
  --language en-US

Authentication

Two bearer-token modes

Clerk session

Browser and dashboard calls use a Clerk bearer token. These routes manage agent-token inventory and return only token previews after creation.

GET /api/v1/agent/tokens

Agent token

CLI and agent calls use a Publr token that starts with pk_live_ or pk_test_. Publishing requires the publish:write scope.

POST /api/v1/agent/publish

CLI

Use @publr/cli

The CLI prints JSON, does not store secrets, and reads PUBLR_API_URL plus PUBLR_API_TOKEN from the environment unless flags are supplied.

npx @publr/cli whoami

npx @publr/cli publish ./index.html \
  --slug agent-demo \
  --name "Agent demo" \
  --content-type text/html \
  --language en-US

Direct API

Call the publish API

Direct clients must send a fresh UUID in Idempotency-Key for each publish request. The body is strict JSON and extra fields are rejected.

Check identity

curl -sS https://api.publr.host/api/v1/agent/whoami \
  -H "Authorization: Bearer $PUBLR_API_TOKEN"

Publish one file

curl -sS https://api.publr.host/api/v1/agent/publish \
  -H "Authorization: Bearer $PUBLR_API_TOKEN" \
  -H "Idempotency-Key: 7f1d4b1a-2c3e-4f5a-8b90-123456789abc" \
  -H "content-type: application/json" \
  -d '{
    "name": "Agent demo",
    "slug": "agent-demo",
    "filename": "index.html",
    "contentType": "text/html",
    "content": "<!doctype html><h1>Published by an agent</h1>",
    "sessionFingerprint": "7f1d4b1a-2c3e-4f5a-8b90-123456789abc",
    "language": "en-US"
  }'

Responses

Publish result

A successful publish returns the created resource ids plus the public sandbox URL. Store the URL in the agent transcript and hand it back to the user.

{
  "projectId": "j57...",
  "workspaceId": "k29...",
  "assetId": "m44...",
  "deploymentId": "n81...",
  "hostname": "agent-demo.publr.site",
  "sandboxUrl": "https://agent-demo.publr.site/"
}

Reference

Implemented endpoints

Method	Path	Auth	Use
GET	/api/v1/agent/whoami	Agent token	Inspect the current agent token, user, scopes, and Convex-auth proof.
POST	/api/v1/agent/publish	Agent token	Publish one inline UTF-8 file and receive a live sandbox URL.
GET	/api/v1/agent/tokens	Clerk session	List caller-owned token previews with cursor pagination.
POST	/api/v1/agent/tokens	Clerk session	Create a revocable token. The raw secret is returned once.
POST	/api/v1/agent/tokens/{id}/revoke	Clerk session	Revoke a caller-owned token by id.

Schemas

Request fields

Inputs are strict. Unknown fields are rejected, and backend routes validate every request before writing projects, assets, tokens, or deployment records.

Publish request

name required

Human-readable project name, up to 120 characters.

slug required

Public sandbox slug, 3 to 50 lowercase letters, numbers, or hyphens.

filename required

Inline file name written to storage, up to 255 characters.

contentType required

MIME type for the inline file, such as text/html.

content required

UTF-8 file content sent in the JSON body.

sessionFingerprint required

Stable request fingerprint, normally matching the idempotency key.

language required

Currently pt-BR or en-US.

Create token request

label optional

Optional name shown in token inventory.

scopes optional

Allowed values are publish:write and tokens:manage.

expiresAt optional

Optional ISO date-time expiration.

Errors

Error model

Error responses include a stable correlationId. Log that id in agent traces so failed publishes can be matched to server-side diagnostics without logging raw request bodies or token secrets.

Status	Code	Meaning
400	validation/failed	Invalid JSON, missing fields, or fields outside the strict schema.
401	auth_required	Missing, expired, revoked, or malformed bearer token.
403	auth_forbidden	The token is valid but lacks the required scope or permission.
409	slug_unavailable	The requested sandbox slug is already reserved or deployed.
413	file_too_large	Inline content exceeds the authenticated user plan limit.
415	validation/blocked	Synchronous security checks blocked the submitted content.
500	config_missing	A required server-side operational parameter is missing.

Discovery

Machine-readable docs

Publr exposes standard discovery files so agents can find the API, load context, and select the right integration path without scraping the marketing site.

Agent manifest /.well-known/agent.json Agent card /.well-known/agent-card.json Plugin manifest /.well-known/ai-plugin.json API catalog /.well-known/api-catalog

Limits

Current surface area

Agent publishing currently accepts one inline UTF-8 file per request. File-size enforcement, moderation, slug ownership, and quota checks come from Publr's existing upload pipeline and plan configuration.

Not part of this first surface

Multi-file Sites, Drive-style private storage, hosted key provisioning, and billing APIs are not documented here because they are outside the implemented public agent API.