Publish an artifact

POST

/v1/publish

const url = 'https://shareout.site/v1/publish';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"My App","slug":"my-app","entrypoint":"index.html","visibility":"public","files":[{"path":"index.html","content":"<!DOCTYPE html><h1>Hello</h1>","mime":"text/html","encoding":"utf8"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://shareout.site/v1/publish \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "My App", "slug": "my-app", "entrypoint": "index.html", "visibility": "public", "files": [ { "path": "index.html", "content": "<!DOCTYPE html><h1>Hello</h1>", "mime": "text/html", "encoding": "utf8" } ] }'

Create a new artifact or push a new version of an existing one. Every files[].path must be a safe relative path (see FileEntry.path); an unsafe one returns 400 INVALID_PATH with a hint naming it.

Authorizations

bearerAuth

Request Body^required

application/json

object

name

required

Display name.

string

slug

URL slug. Auto-generated if omitted.

string

entrypoint

string

default: index.html

files

required

Array<object>

object

path

required

Relative path with “/” between folders. No “..”, no leading “/”, no backslash, no empty or “.” segments (e.g. “a//b”, “./x”), no control characters, at most 512 characters. An unsafe path is rejected with 400 INVALID_PATH; the hint names it.

string

<= 512 characters

content

required

string

mime

string

encoding

string

Allowed values: utf8 base64

size_bytes

integer

visibility

‘unlisted’ was retired 2026-07 — still accepted as input and treated as ‘public’.

string

Allowed values: public workspace private

mobile_html

string

pwa

object

enabled

boolean

name

string

short_name

string

<= 12 characters

icon

Data URL or absolute URL to a PNG icon.

string

access_policy

Row-level access policy for per-viewer data filtering: { version: 1, field, default, rules, queries? }. queries maps a name to { connection, provider, endpoint, params } — the Data Platform queries scoped viewers may run.

object

agent

Turns on the visitor chat agent.

object

enabled

boolean

default: true

systemPrompt

string

model

string

maxTokens

integer

temperature

number

contextJson

boolean

default: true

contextTables

Array<string>

message

Optional change note for this version, shown in the version history. When a new version is published without one, a short “what changed” note may be generated in the background (message_source: ai), unless the workspace turned off ai.version_summaries.

string

<= 500 characters

Examples

minimal

Single HTML file

{
  "name": "My App",
  "slug": "my-app",
  "entrypoint": "index.html",
  "visibility": "public",
  "files": [
    {
      "path": "index.html",
      "content": "<!DOCTYPE html><h1>Hello</h1>",
      "mime": "text/html",
      "encoding": "utf8"
    }
  ]
}

Responses

201

Published. Check visibility — when it is more private than asked, visibility_downgraded is true and notice says why; tell the user.

application/json

object

artifact

object

string

version

object

string

version_no

integer

deployment

object

slug

string

url

string format: uri

subdomain_url

Preferred share URL for workspace artifacts (https://{workspace}.shareout.site/{slug}/). Omitted for personal artifacts.

string format: uri

mobile_url

string format: uri

editor_readiness

Advisory HTML editor-readiness profile (HTML artifacts only). Never blocks publishing.

object

manifest

string

Allowed values: valid invalid missing

outline

boolean

counts

object

pages

integer

bindings

integer

templates

integer

summary

object

errors

integer

warnings

integer

infos

integer

findings

Array<object>

object

rule

string

level

string

message

string

suggestion

string

disables

string

pwa

object

manifest_url

string format: uri

installable

boolean

visibility

‘unlisted’ was retired 2026-07 — still accepted as input and treated as ‘public’.

string

Allowed values: public workspace private

visibility_downgraded

True when the page came out more private than requested (instance policy, account without a verified email, public-artifact cap, or a moderation hold). A publish with no visibility counts as asking for public.

boolean

requested_visibility

Present with visibility_downgraded.

string

Allowed values: public

notice

Human-readable reason the publish was adjusted (governance, caps, email gate, instance policy).

string

approval_required

Present when workspace policy requires teammate approval before going open.

object

required

Number of approvers the requester must nominate.

integer

artifact_id

string

moderation

object

status

string

Allowed values: approved pending blocked

reason

string

message

string

requested_visibility

string

Allowed values: public workspace private

Example

{
  "editor_readiness": {
    "manifest": "valid"
  },
  "visibility": "public",
  "requested_visibility": "public",
  "moderation": {
    "status": "approved",
    "requested_visibility": "public"
  }
}

400

Invalid request

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

401

Authentication required

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

403

Access denied

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

409

Slug taken or version conflict

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

413

Storage limit reached (STORAGE_LIMIT_EXCEEDED).

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

429

Rate limit reached (RATE_LIMIT_EXCEEDED on publish / account creation / AI routes, RATE_LIMITED on the data plane). Wait for Retry-After / reset.

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

500

Unexpected server failure. Retry once; if it fails again, file a ticket with POST /v1/support/tickets quoting request_id.

application/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

Publish an artifact

Authorizations

Request Bodyrequired

Examples

Responses

201

Example

400

Example

401

Example

403

Example

409

Example

413

Example

429

Example

500

Example

Request Body^required