Artifact Publisher

Publish self-contained HTML as version 1; return a share link. Optional Idempotency-Key HTTP header. Limit 10 MiB UTF-8; larger on some paid plans. No network in sandbox; inline assets. Free: 5 active artifacts, 50 versions. For styling, add <meta name="ap-theme" content="firn"> to <head>; call get_authoring_guide for themes and layout classes.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "title": {
      "type": "string",
      "maxLength": 200
    },
    "html": {
      "type": "string",
      "minLength": 1
    },
    "summary": {
      "type": "string",
      "maxLength": 1000
    },
    "expires_at": {
      "description": "ISO 8601 UTC, 60 s to 365 days ahead; null = never; omit = workspace default.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "comments_enabled": {
      "description": "Defaults to the workspace setting.",
      "type": "boolean"
    },
    "visibility": {
      "description": "public = anyone with link, no sign-in, not listed or searchable (alias: unlisted); private = owner only; allowlist = listed primary emails, account required. Default: public. `team` (some workspaces) = members only, may be the default; owners and admins can open private and allowlist pages (audited).",
      "type": "string",
      "enum": [
        "public",
        "private",
        "allowlist",
        "unlisted",
        "team"
      ]
    },
    "allowed_emails": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 320
      },
      "description": "Required for allowlist; omit otherwise."
    }
  },
  "required": [
    "html"
  ],
  "additionalProperties": false
}

Append a new immutable version to an existing artifact. `expected_version` must equal the current version; the share link moves to the new version; earlier versions stay readable at their pinned URL. Optional `title` renames; with no `html` only the title changes. Each version counts toward the free 50 version cap. For styling, add <meta name="ap-theme" content="firn"> to <head>; call get_authoring_guide for themes and layout classes.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "html": {
      "type": "string",
      "minLength": 1
    },
    "title": {
      "type": "string",
      "maxLength": 200
    },
    "expected_version": {
      "type": "integer",
      "minimum": 1
    },
    "release_note": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "artifact_id",
    "expected_version"
  ],
  "additionalProperties": false
}

Change an artifact's access mode without a new version. For accountless coworkers use public, not allowlist.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "visibility": {
      "type": "string",
      "enum": [
        "public",
        "private",
        "allowlist",
        "unlisted",
        "team"
      ],
      "description": "Modes as in publish_artifact.visibility."
    },
    "allowed_emails": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 320
      },
      "description": "Required for allowlist; omit otherwise."
    }
  },
  "required": [
    "artifact_id",
    "visibility"
  ],
  "additionalProperties": false
}

Read reviewer comments on an artifact, oldest first; use after sharing or to poll. Filters: unresolved_only, since; version (default current) picks the version anchor_status is checked against. Page with limit and cursor. Returns comments, unresolved_count, next_cursor.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Page size; default 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Pass next_cursor.",
      "type": "string",
      "maxLength": 2048
    },
    "version": {
      "type": "integer",
      "minimum": 1
    },
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "unresolved_only": {
      "type": "boolean"
    },
    "since": {
      "type": "string"
    }
  },
  "required": [
    "artifact_id"
  ],
  "additionalProperties": false
}

Reply once to a comment (a second reply fails with conflict); resolve: true also marks it resolved. Anyone who can open the artifact can read the reply. Refused on revoked or expired artifacts. Returns the comment.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "comment_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "message": {
      "type": "string",
      "maxLength": 4000
    },
    "resolve": {
      "type": "boolean"
    }
  },
  "required": [
    "comment_id",
    "message"
  ],
  "additionalProperties": false
}

List artifacts in this key's workspace, newest first, with unresolved comment counts. Pass `next_cursor` back as `cursor` to page.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "maxLength": 512
    }
  },
  "additionalProperties": false
}

Stop serving this artifact (410 Gone). Cannot undo; viewed copies exist.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "reason": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "artifact_id"
  ],
  "additionalProperties": false
}

Read or update workspace defaults (comments_enabled, default_expiry_seconds, default_artifact_title); pass empty settings to read. Platform guardrails are refused with an error: max_artifact_bytes, storage_bytes_limit, monthly_versions_limit, rate_limits, comment_rate_limit, publish_rate_limit, isolation, origins, artifact_origin, control_origin, storage_key_prefix, object_key_prefix, security_headers, content_security_policy. Not available in every workspace.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "settings": {
      "type": "object",
      "properties": {
        "comments_enabled": {
          "type": "boolean",
          "description": "false = no link may enable comments."
        },
        "default_expiry_seconds": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 60,
              "maximum": 31536000
            },
            {
              "type": "null"
            }
          ],
          "description": "Used when publish omits expires_at; null = never."
        },
        "default_artifact_title": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ],
          "description": "Used when publish omits title."
        }
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "settings"
  ],
  "additionalProperties": false
}

Read an artifact's state. Shared JSON key/value state, synced to viewers across versions (page JS: ArtifactRelayState). Last write wins per key. Limits: 200 keys, 16 KiB per value, 64 KiB total.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "artifact_id"
  ],
  "additionalProperties": false
}

Set the given keys atomically; other keys stay. Null is stored, not deleted. Shared JSON key/value state, synced to viewers across versions (page JS: ArtifactRelayState). Last write wins per key. Limits: 200 keys, 16 KiB per value, 64 KiB total. Page JS: ArtifactRelayState.subscribe(fn)/set(k,v)/patch(obj); callbacks get {revision, values, resetAt}; set/patch reject on failure; whole-value writes, no increments or nested merges.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1
    },
    "values": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "additionalProperties": {},
      "description": "Keys to JSON values; depth max 16."
    }
  },
  "required": [
    "artifact_id",
    "values"
  ],
  "additionalProperties": false
}

Clear all state, including board values; HTML is unchanged. Shared JSON key/value state, synced to viewers across versions (page JS: ArtifactRelayState). Last write wins per key. Limits: 200 keys, 16 KiB per value, 64 KiB total.

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "minLength": 1
    },
    "artifact_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "artifact_id"
  ],
  "additionalProperties": false
}

Read before writing HTML or a routine: themes, ap-* layout classes, an example page, the snippet, size, sandbox and routine rules. Optional theme (firn, firn@1) is validated and returned as selected.

{
  "type": "object",
  "properties": {
    "theme": {
      "description": "Validate one theme (firn, firn@1).",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  },
  "additionalProperties": false
}