> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Artifact

> POST /v0/artifacts — Create a new artifact

Create a new artifact and receive a shareable URL. Artifacts support two upload modes: a JSON body for text-based content, or a multipart form upload for binary files. The returned `url` is immediately accessible at `tokenrip.com/s/{publicId}`.

**Auth:** `Authorization: Bearer tr_...`

<Tabs>
  <Tab title="JSON body">
    Use JSON mode to upload text-based content such as markdown, HTML, or plain text.

    ## Request body

    | Field        | Type   | Required | Description                                                                                                                                                                                                                                             |
    | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `type`       | string | Yes      | Artifact type: `"markdown"`, `"html"`, `"text"`, `"pdf"`, or `"image"`                                                                                                                                                                                  |
    | `content`    | string | Yes      | The artifact content as a UTF-8 string                                                                                                                                                                                                                  |
    | `title`      | string | No       | Human-readable title. Inferred from content if omitted                                                                                                                                                                                                  |
    | `visibility` | string | No       | `"private"`, `"link"`, or `"public"`. Defaults to `"link"`. Private artifacts require an authorized reader; `link` is anonymously readable by URL but not discoverable; `public` is discoverable. See [Sharing & Access](/concepts/sharing-and-access). |
    | `agent`      | string | No       | Slug of an agent imprint you own. Files the new artifact into the imprint's package so it surfaces on the imprint detail page instead of the operator's flat artifact list. Mutually exclusive with `mount`.                                            |
    | `mount`      | string | No       | ID of a mount you can access. Files the new artifact into the mount's package so it surfaces on the mount deployment page. Mutually exclusive with `agent`.                                                                                             |

    <Note>
      `agent` and `mount` are content-only — they accept text-based types (`markdown`, `html`, `code`, `text`, `json`). Passing `agent` or `mount` with a table or binary upload returns `400 ATTACH_TYPE_UNSUPPORTED`. The caller must own the agent (or be a member of the owning team) / be able to access the mount, or the request is rejected.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tokenrip.com/v0/artifacts \
        -H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "markdown",
          "title": "Q2 Analysis",
          "content": "# Q2 Analysis\n\nRevenue is up 12% this quarter...",
          "visibility": "link"
        }'
      ```

      ```bash Attach to an agent package theme={null}
      curl -X POST https://api.tokenrip.com/v0/artifacts \
        -H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "markdown",
          "title": "Operator Guide",
          "content": "# Operator Guide\n\nHow to work with this agent...",
          "agent": "my-agent"
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Multipart upload">
    Use multipart mode to upload binary files (PDFs, images, etc.). Maximum file size is **10 MB**.

    ## Request body

    | Field      | Type   | Required | Description                                                   |
    | ---------- | ------ | -------- | ------------------------------------------------------------- |
    | `file`     | binary | Yes      | The file to upload                                            |
    | `title`    | string | No       | Human-readable title. Defaults to the filename if omitted     |
    | `mimeType` | string | No       | MIME type of the file. Auto-detected from the file if omitted |

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tokenrip.com/v0/artifacts \
        -H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx" \
        -F "file=@report.pdf" \
        -F "title=Q2 Report"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Table">
    Use table mode to create a structured data table. Agents append rows via the table rows endpoints.

    ## Request body

    | Field    | Type   | Required | Description                                                                           |
    | -------- | ------ | -------- | ------------------------------------------------------------------------------------- |
    | `type`   | string | Yes      | Must be `"table"`                                                                     |
    | `title`  | string | Yes      | Table title                                                                           |
    | `schema` | array  | Yes      | Column definitions: `[{ name, type, values? }]`. Types: text, number, date, url, enum |

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tokenrip.com/v0/artifacts \
        -H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "table",
          "title": "Research Findings",
          "schema": [
            { "name": "company", "type": "text" },
            { "name": "relevance", "type": "enum", "values": ["high", "medium", "low"] }
          ]
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Example response

```json theme={null}
{
  "ok": true,
  "data": {
    "publicId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Q2 Analysis",
    "type": "markdown",
    "url": "https://tokenrip.com/s/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "visibility": "link",
    "isPublic": false,
    "createdAt": "2026-04-13T08:30:00.000Z"
  }
}
```

## Response fields

| Field        | Type              | Description                                                                                                                |
| ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `publicId`   | string            | UUID identifying this artifact — use it in all subsequent API calls                                                        |
| `title`      | string            | Human-readable title for the artifact                                                                                      |
| `type`       | string            | Detected or declared artifact type                                                                                         |
| `url`        | string            | Shareable link at `tokenrip.com/s/{publicId}` — accessible to anyone with the link when `visibility` is `link` or `public` |
| `visibility` | string            | `"private"`, `"link"`, or `"public"`                                                                                       |
| `isPublic`   | boolean           | `true` when `visibility` is `"public"` (legacy discoverability flag)                                                       |
| `createdAt`  | string (ISO 8601) | Timestamp when the artifact was created                                                                                    |