Developer documentation
Hosted MCP reference
Connect an MCP client to publish, inspect, update, and share static artifacts, and work with reader feedback.
Endpoint and transport
- Server URL
https://sendartifact.com/mcp- Transport
- Streamable HTTP over HTTPS. Send MCP JSON-RPC requests with POST. The server returns JSON responses and does not require a persistent session.
- Tool discovery
- Use MCP
tools/list. The exact tool definitions, including input and output schemas, are also available as JSON.
Opening /mcp with a browser GET returns a method error; use an MCP client to connect.
Authentication and access
Discovery and temporary publishing are available without an account. publish_artifact can create an unlisted seven-day link with destination: "temporary"; its separate claim link is private, and the user opens it in a browser and signs in to keep the artifact. No tool accepts a claim link or token. Permanent publishing and all other account tools require a Send Artifact account and browser OAuth consent.
The server supports OAuth 2.0 authorization code with PKCE S256 and dynamic client registration. Clients discover the authorization server from the protected-resource metadata and authorization-server metadata. Registration is automatic; users do not need to supply a client ID, client secret, or API key. A protected tool called without authorization returns an OAuth challenge.
Scopes requested by account tools:
artifacts:readartifacts:writeartifacts:accessartifacts:deletecomments:write
See connection setup for assistant-specific sign-in steps. Reviewer credentials belong only in private directory fields.
Tool behavior
Updates publish a complete file bundle and require the latest baseRevision; stale revisions return VERSION_CONFLICT. Read the current files before replacing them. Deletion requires confirm: true. Readers' comments are available to the author through the feedback tools; the assistant addresses them when the author asks.
get_identity— Returns the connected account and selected publishing handle. Account sign-in and creation use browser-based OAuth.list_artifacts— Find your artifacts by title or slug. Returns bounded current summaries, with no readership or history data.get_artifact— Returns current metadata, file inventory, sharing settings and revision for one artifact.read_artifact— Returns a segment of one current artifact file without the injected comment bridge. Continuations require expectedRevision; historical versions are not available.publish_artifact— Creates a temporary artifact or creates or updates an account artifact from complete static HTML or a complete file bundle. Account creation defaults private; updates require baseRevision and preserve settings. Share the returned url exactly as given. Temporary publication returns a seven-day share URL and a separate private claim link, which the user opens in a browser to keep the artifact. The server does not fetch local paths or URLs. Artifacts and uploaded files are not intended for protected health information, government identifiers, payment-card data, biometric identifiers, passwords, API keys, or authentication codes.set_access— Changes supplied sharing settings. Omitted settings remain unchanged; supplied grants replace the entire list, and an empty grants list clears it.get_comments— Returns full comment bodies, anchors and replies. Pagination covers additional threads and replies; a commentId selects one thread regardless of status. Results are bounded to 64 KiB.reply_comment— Adds one message to an existing feedback thread without resolving or reopening it. Feedback is not intended for protected health information, government identifiers, payment-card data, biometric identifiers, passwords, API keys, or authentication codes.resolve_comment— Marks a feedback thread resolved without adding a message. An already-resolved thread remains unchanged.delete_artifact— Permanently deletes an authorized artifact when confirm is true.
Tool schemas
These definitions are generated from the same contract used by the live MCP server. Each output schema includes the structured error shape. The live tools/list response is authoritative if this page and a deployed server ever differ.
get_identity
Returns the connected account and selected publishing handle. Account sign-in and creation use browser-based OAuth.
Access: OAuth 2.0 · artifacts:read
Input schema
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1,
"maxLength": 254
},
"handles": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
}
},
"defaultHandle": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
{
"type": "null"
}
]
}
},
"required": [
"email",
"handles",
"defaultHandle"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}list_artifacts
Find your artifacts by title or slug. Returns bounded current summaries, with no readership or history data.
Access: OAuth 2.0 · artifacts:read
Input schema
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"offset": {
"type": "integer",
"minimum": 0,
"default": 0
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 30
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"artifacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
"description": "The artifact's name, used to reference it in later calls. Not a shareable link."
},
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The link to give readers. Share it exactly as returned; never build a link from handle and slug."
},
"title": {
"type": "string",
"maxLength": 160
},
"version": {
"type": "integer",
"minimum": 1
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public",
"restricted"
],
"description": "restricted reports existing domain-based access. It is not owner-only private access or a selectable visibility; updates preserve its access rules unless set_access explicitly changes visibility."
},
"bytes": {
"type": "integer",
"minimum": 0
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
}
},
"required": [
"handle",
"slug",
"url",
"title",
"version",
"revision",
"visibility",
"bytes"
],
"additionalProperties": false
},
"maxItems": 100
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"artifacts",
"nextOffset"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}get_artifact
Returns current metadata, file inventory, sharing settings and revision for one artifact.
Access: OAuth 2.0 · artifacts:read
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
}
},
"required": [
"artifact"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
"description": "The artifact's name, used to reference it in later calls. Not a shareable link."
},
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The link to give readers. Share it exactly as returned; never build a link from handle and slug."
},
"title": {
"type": "string",
"maxLength": 160
},
"version": {
"type": "integer",
"minimum": 1
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public",
"restricted"
],
"description": "restricted reports existing domain-based access. It is not owner-only private access or a selectable visibility; updates preserve its access rules unless set_access explicitly changes visibility."
},
"bytes": {
"type": "integer",
"minimum": 0
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
},
"entryFile": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"files": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
}
},
"grants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"domain"
]
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
}
},
"sourceUrl": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 2048
},
{
"type": "null"
}
]
},
"sourceCapturedAt": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
]
}
},
"required": [
"handle",
"slug",
"url",
"title",
"version",
"revision",
"visibility",
"bytes",
"entryFile",
"files",
"grants",
"requireEmail",
"comments"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}read_artifact
Returns a segment of one current artifact file without the injected comment bridge. Continuations require expectedRevision; historical versions are not available.
Access: OAuth 2.0 · artifacts:read
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"path": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"encoding": {
"type": "string",
"enum": [
"utf8",
"base64"
],
"default": "utf8"
},
"offset": {
"type": "integer",
"minimum": 0,
"default": 0
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 32768,
"default": 12000
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
}
},
"required": [
"artifact"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"offset": {
"minimum": 1
}
},
"required": [
"offset"
]
},
"then": {
"required": [
"expectedRevision"
]
}
}
]
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
"description": "The artifact's name, used to reference it in later calls. Not a shareable link."
},
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The link to give readers. Share it exactly as returned; never build a link from handle and slug."
},
"title": {
"type": "string",
"maxLength": 160
},
"version": {
"type": "integer",
"minimum": 1
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public",
"restricted"
],
"description": "restricted reports existing domain-based access. It is not owner-only private access or a selectable visibility; updates preserve its access rules unless set_access explicitly changes visibility."
},
"bytes": {
"type": "integer",
"minimum": 0
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
},
"path": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"encoding": {
"type": "string",
"enum": [
"utf8",
"base64"
]
},
"content": {
"type": "string",
"maxLength": 32768
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"handle",
"slug",
"url",
"title",
"version",
"revision",
"visibility",
"bytes",
"path",
"encoding",
"content",
"nextOffset"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}publish_artifact
Creates a temporary artifact or creates or updates an account artifact from complete static HTML or a complete file bundle. Account creation defaults private; updates require baseRevision and preserve settings. Share the returned url exactly as given. Temporary publication returns a seven-day share URL and a separate private claim link, which the user opens in a browser to keep the artifact. The server does not fetch local paths or URLs. Artifacts and uploaded files are not intended for protected health information, government identifiers, payment-card data, biometric identifiers, passwords, API keys, or authentication codes.
Access: No authentication (temporary publishing only); OAuth 2.0 · artifacts:write
Input schema
{
"type": "object",
"properties": {
"destination": {
"type": "string",
"enum": [
"account",
"temporary"
]
},
"html": {
"type": "string",
"minLength": 1,
"maxLength": 26214400,
"description": "Complete HTML. The decoded-byte limit still applies; stored as index.html, or the existing sole HTML path on update."
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"content": {
"type": "string",
"maxLength": 34952536
},
"encoding": {
"type": "string",
"enum": [
"utf8",
"base64"
]
}
},
"required": [
"path",
"content",
"encoding"
],
"additionalProperties": false
},
"maxItems": 1000,
"minItems": 1,
"description": "Entire replacement bundle including unchanged assets. Aggregate decoded bytes <=25 MiB; JSON request <=40 MiB."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"baseRevision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"allowRemoveFiles": {
"type": "boolean",
"default": false
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public"
]
},
"comments": {
"type": "boolean"
},
"sourceUrl": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"sourceCapturedAt": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"destination"
],
"additionalProperties": false,
"allOf": [
{
"oneOf": [
{
"required": [
"html"
],
"not": {
"required": [
"files"
]
}
},
{
"required": [
"files"
],
"not": {
"required": [
"html"
]
}
}
]
},
{
"if": {
"properties": {
"destination": {
"type": "string",
"const": "account"
}
},
"required": [
"destination"
]
},
"then": {
"required": [
"artifact"
]
},
"else": {
"not": {
"anyOf": [
{
"required": [
"artifact"
]
},
{
"required": [
"handle"
]
},
{
"required": [
"baseRevision"
]
},
{
"required": [
"allowRemoveFiles"
]
},
{
"required": [
"visibility"
]
},
{
"required": [
"comments"
]
},
{
"required": [
"sourceUrl"
]
},
{
"required": [
"sourceCapturedAt"
]
}
]
}
}
},
{
"if": {
"required": [
"baseRevision"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"visibility"
]
},
{
"required": [
"comments"
]
}
]
}
}
}
]
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
"description": "The artifact's name, used to reference it in later calls. Not a shareable link."
},
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The link to give readers. Share it exactly as returned; never build a link from handle and slug."
},
"title": {
"type": "string",
"maxLength": 160
},
"version": {
"type": "integer",
"minimum": 1
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public",
"restricted"
],
"description": "restricted reports existing domain-based access. It is not owner-only private access or a selectable visibility; updates preserve its access rules unless set_access explicitly changes visibility."
},
"bytes": {
"type": "integer",
"minimum": 0
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"root-relative-url",
"base-tag",
"more"
]
},
"path": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"count": {
"type": "integer",
"minimum": 1
},
"sample": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
},
"required": [
"code"
],
"additionalProperties": false
},
"maxItems": 21
},
"warning": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"handle",
"slug",
"url",
"title",
"version",
"revision",
"visibility",
"bytes"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"claimUrl": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"expiresAt": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"version": {
"type": "integer",
"minimum": 1
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"bytes": {
"type": "integer",
"minimum": 0
},
"guidance": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"root-relative-url",
"base-tag",
"more"
]
},
"path": {
"type": "string",
"minLength": 1,
"description": "Relative path inside the static bundle; existing service path and file-type restrictions apply."
},
"count": {
"type": "integer",
"minimum": 1
},
"sample": {
"type": "string",
"minLength": 1,
"maxLength": 240
}
},
"required": [
"code"
],
"additionalProperties": false
},
"maxItems": 21
}
},
"required": [
"url",
"claimUrl",
"expiresAt",
"version",
"title",
"bytes",
"guidance"
],
"additionalProperties": false
}
]
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}set_access
Changes supplied sharing settings. Omitted settings remain unchanged; supplied grants replace the entire list, and an empty grants list clears it.
Access: OAuth 2.0 · artifacts:access
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public"
]
},
"grants": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 254
},
"maxItems": 100
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
}
},
"required": [
"artifact"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"visibility"
]
},
{
"required": [
"grants"
]
},
{
"required": [
"requireEmail"
]
},
{
"required": [
"comments"
]
}
]
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
"description": "The artifact's name, used to reference it in later calls. Not a shareable link."
},
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The link to give readers. Share it exactly as returned; never build a link from handle and slug."
},
"title": {
"type": "string",
"maxLength": 160
},
"version": {
"type": "integer",
"minimum": 1
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 28,
"pattern": "^ver_[a-f0-9]{24}$",
"description": "Opaque revision returned by a current read or inspection; identifies the artifact and exact stored version."
},
"visibility": {
"type": "string",
"enum": [
"private",
"guests",
"link",
"public",
"restricted"
],
"description": "restricted reports existing domain-based access. It is not owner-only private access or a selectable visibility; updates preserve its access rules unless set_access explicitly changes visibility."
},
"bytes": {
"type": "integer",
"minimum": 0
},
"requireEmail": {
"type": "string",
"enum": [
"none",
"capture",
"verified"
]
},
"comments": {
"type": "boolean"
},
"grants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"domain"
]
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"handle",
"slug",
"url",
"title",
"version",
"revision",
"visibility",
"bytes",
"grants",
"requireEmail",
"comments"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}get_comments
Returns full comment bodies, anchors and replies. Pagination covers additional threads and replies; a commentId selects one thread regardless of status. Results are bounded to 64 KiB.
Access: OAuth 2.0 · artifacts:read
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"status": {
"type": "string",
"enum": [
"open",
"resolved",
"orphaned",
"all"
],
"default": "open"
},
"offset": {
"type": "integer",
"minimum": 0,
"default": 0
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"default": 10
},
"commentId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"replyOffset": {
"type": "integer",
"minimum": 0,
"default": 0
},
"replyLimit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"default": 5
}
},
"required": [
"artifact"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"replyOffset": {
"minimum": 1
}
},
"required": [
"replyOffset"
]
},
"then": {
"required": [
"commentId"
]
}
}
]
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"threads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"status": {
"type": "string",
"enum": [
"open",
"resolved",
"orphaned"
]
},
"version": {
"type": "integer",
"minimum": 1
},
"n": {
"type": "integer",
"minimum": 1
},
"author": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 30
}
},
"required": [
"name",
"kind"
],
"additionalProperties": false
},
"quote": {
"type": "string"
},
"contextBefore": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"contextAfter": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"anchor": {},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 30
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"createdAt": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"resolved": {
"anyOf": [
{
"type": "object",
"properties": {
"at": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"version": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"required": [
"at",
"by",
"version"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"replies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"author": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 30
}
},
"required": [
"name",
"kind"
],
"additionalProperties": false
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"createdAt": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"id",
"author",
"body",
"createdAt"
],
"additionalProperties": false
},
"maxItems": 20
},
"replyCount": {
"type": "integer",
"minimum": 0
},
"nextReplyOffset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"status",
"version",
"n",
"author",
"quote",
"contextBefore",
"contextAfter",
"anchor",
"kind",
"body",
"createdAt",
"resolved",
"replies",
"replyCount",
"nextReplyOffset"
],
"additionalProperties": false
},
"maxItems": 30
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"threads",
"nextOffset"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}reply_comment
Adds one message to an existing feedback thread without resolving or reopening it. Feedback is not intended for protected health information, government identifiers, payment-card data, biometric identifiers, passwords, API keys, or authentication codes.
Access: OAuth 2.0 · comments:write
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"commentId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"pattern": "\\S"
}
},
"required": [
"artifact",
"commentId",
"body"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"reply": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"author": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 30
}
},
"required": [
"name",
"kind"
],
"additionalProperties": false
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"createdAt": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"id",
"author",
"body",
"createdAt"
],
"additionalProperties": false
}
},
"required": [
"reply"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}resolve_comment
Marks a feedback thread resolved without adding a message. An already-resolved thread remains unchanged.
Access: OAuth 2.0 · comments:write
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"commentId": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"artifact",
"commentId"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"commentId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"status": {
"type": "string",
"const": "resolved"
}
},
"required": [
"commentId",
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}delete_artifact
Permanently deletes an authorized artifact when confirm is true.
Access: OAuth 2.0 · artifacts:delete
Input schema
{
"type": "object",
"properties": {
"artifact": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "The artifact's slug (its name) with the selected handle, handle/slug, or a url Send Artifact returned for it."
},
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"confirm": {
"type": "boolean",
"const": true
}
},
"required": [
"artifact",
"confirm"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"oneOf": [
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
},
"deleted": {
"type": "boolean",
"const": true
}
},
"required": [
"handle",
"slug",
"deleted"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"status",
"retryable"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}