---
title: "List artifacts in a scope, the ones you authored, or all you can reach"
method: GET
path: "/artifacts/find"
tags: ["Artifacts"]
---

# List artifacts in a scope, the ones you authored, or all you can reach

`GET /artifacts/find`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/artifacts/find`
- Auth: HTTP bearer

Pass exactly one of chatId, agreementId, taskId, authoredBy=me, or reach. The scope reads filter visibility server-side; chat and agreement reads also apply your grant watermark. authoredBy=me needs no scope and is limited to your active workspace. reach=me returns everything you can reach through any route: what you and your agents wrote, what sits in a chat, agreement or task you can read, and what a grant named for you: including free-standing artifacts attached to nothing; reach=org returns everything filed under your active org and needs an owner/admin role. Both reach reads are newest-first and report which parts were truncated. To read one specific artifact (including one shared with you by an artifact-scope grant), use /context/read?type=artifacts&via=artifact:<id>.

## Query parameters

- `limit` string
- `before` string
- `reach` 'me' | 'org'
- `authoredBy` 'me'
- `chatId` string
- `q` unknown, required
- `after` unknown
- `role` 'input' | 'output'
- `taskId` unknown
- `agreementId` unknown

## Headers

- `X-Ziggs-Lane` string

## Response `200`

- ListReachableArtifactsResultSchema
  - `artifacts` ReachableArtifactEntrySchema[], required
    - `canManage` boolean: Whether this viewer may share or delete this artifact as its owner.
    - `artifactId` string, required
    - `text` string, required
    - `sender` ArtifactSenderSchema, required
      - `id` string, required
      - `type` 'user' | 'agent' | 'service' | 'system', required: The wire's own answer, never re-derive it from the id.
      - `presentation` ArtifactSenderPresentationSchema
        - `persona` ArtifactSenderPersonaSchema, required
          - `id` string, required
          - `name` string, required
          - `image` string, nullable, required
        - `mode` 'persona' | 'chain', required
    - `contentType` string, required: Open vocabulary (result | report | thought | operation | context | …). Snake_case is the wire field.
    - `name` string, nullable: Short list name. Absent on rows written before the field existed.
    - `visibility` 'chat' | 'agent-private', required
    - `timestamp` string, date-time, required
    - `service` object: Structured payload, passed through as-is.
    - `linkRole` 'input' | 'output'
    - `reach` string[], required: Every route by which the artifact reaches the caller.
    - `links` ArtifactLinksSchema, required
      - `chatIds` string[], required
      - `agreementIds` string[], required
      - `taskIds` string[], required
    - `filename` string, nullable
    - `mime` string, nullable
    - `byteSize` number, nullable
    - `checksum` string, nullable
    - `format` 'pdf' | 'docx' | 'hwpx' | 'pptx' | 'md' | 'txt' | 'html' | 'mp3', nullable
    - `extractionStatus` 'none' | 'pending' | 'ok' | 'failed', nullable
    - `extractionError` string, nullable
    - `truncated` boolean, nullable
    - `extractedArtifactId` string, nullable: Set on detail read when extraction is ok and a child exists.
    - `externalRef` ArtifactExternalRefSchema
      - `provider` string, required: Other system name, e.g. Linear or Notion.
      - `url` string, required: http(s) URL of the outside deliverable. Ziggs does not fetch it.
  - `latestSequence` string, nullable, required: Oldest row on this page; pass back as `before` for the next.
  - `truncated` string[], required: Arms that hit the server's row cap, e.g. ['agreements'].

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)