Skip to content
Kindgi

List artifact metadata

View as Markdown
GET
/v1/artifacts
curl --request GET \
  --url 'https://example.com/v1/artifacts?limit=25' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Metadata rows only (no bytes). Filters: ?ownerRunId=, ?projectId=, ?contentType=, ?tag.<key>=<value> (repeatable — every provided tag must match as AND). Sort order is binding-defined (typically createdAt desc, blobId desc). With authorization on, only artifacts in projects the caller can read are listed.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

ownerRunId
string format: uuid

Filter to blobs produced by this RunId.

contentType
string

Filter by exact content-type match.

projectId
string

Filter to the artifacts of one project.

Responses

Section titled “Responses”

200

Section titled “200”

Page of blob metadata.

Media typeapplication/json
object
data
required
Array<object>
object
blobId
required

ArtifactId — opaque branded string (a UUID).

string
tenantId
required
string format: uuid
name
required

Caller-supplied filename or logical name.

string
contentType
required

MIME type as declared by the uploader. Framework does NOT sniff content-type server-side.

string
size
required

Byte length of the persisted body.

integer
hash
required

Sha256 of the body, hex-encoded, lowercase (64 chars).

string
/^[0-9a-f]{64}$/
tags
required

Free-form caller-supplied labels. Filterable on list via ?tag.<key>=<value>.

object
key
additional properties
string
ownerRunId

Optional back-ref to the RunId that produced this blob.

string format: uuid
projectId

The project the artifact belongs to: its owner run’s, else the upload’s projectId, else the tenant’s default project. Reading it needs read there; deleting it, write. Absent on blobs stored before projects were recorded.

string
createdBy

Who uploaded it: user:<id> or service_account:<id>.

string
createdAt
required
string format: date-time
bucket

The bucket of the blob’s S3-compatible address (/s3/{bucket}/{key}). Present, with key, when the server’s storage gives the blob one: an object put through /s3 has the bucket and key it was put under, and an upload through POST /v1/artifacts conventionally has bucket artifacts and its blobId as the key.

string
key

The key of the blob’s S3-compatible address (/s3/{bucket}/{key}). Present, with bucket, when the server’s storage gives the blob one.

string
nextCursor
string
hasMore
required
boolean
Examplegenerated
{
  "data": [
    {
      "blobId": "example",
      "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "name": "example",
      "contentType": "example",
      "size": 1,
      "hash": "example",
      "tags": {
        "additionalProperty": "example"
      },
      "ownerRunId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "projectId": "example",
      "createdBy": "example",
      "createdAt": "2026-04-15T12:00:00Z",
      "bucket": "example",
      "key": "example"
    }
  ],
  "nextCursor": "example",
  "hasMore": true
}

400

Section titled “400”

Malformed query parameter (e.g. empty tag. key).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also