Gumloop Artifacts API
The Artifacts API from Gumloop — 2 operation(s) for artifacts.
OpenAPI Specification
openapi: 3.0.0
info:
title: Public Agents Artifacts API
version: 1.0.0
servers:
- url: https://api.gumloop.com/api/v1
tags:
- name: Artifacts
paths:
/agents/{agent_id}/artifacts:
get:
summary: List artifacts
description: List artifacts (files) produced by an agent. Optionally scope to a specific session, search by filename, sort, and paginate.
operationId: listArtifacts
tags:
- Artifacts
x-codeSamples:
- lang: bash
label: cURL
source: "curl 'https://api.gumloop.com/api/v1/agents/AGENT_ID/artifacts?page_size=20' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n"
- lang: python
label: Python
source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.artifacts.list(agent_id=\"AGENT_ID\")\nfor artifact in response.artifacts:\n print(artifact.id, artifact.filename)\n"
parameters:
- in: path
name: agent_id
required: true
schema:
type: string
description: ID of the agent whose artifacts to list.
- in: query
name: session_id
required: false
schema:
type: string
description: Filter to artifacts produced within a specific session.
- in: query
name: search_query
required: false
schema:
type: string
description: Case-insensitive substring match against the artifact filename.
- in: query
name: sort_order
required: false
schema:
type: string
default: newest
description: Sort order for results. Defaults to `newest`.
- in: query
name: page_size
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 100
description: Number of artifacts to return per page. Clamped to 1–100.
- in: query
name: cursor
required: false
schema:
type: string
description: Opaque pagination cursor returned by a prior call as `next_cursor`.
responses:
'200':
description: Artifacts matching the provided filters.
content:
application/json:
schema:
type: object
properties:
artifacts:
type: array
items:
type: object
properties:
id:
type: string
description: Unique artifact identifier.
example: art_aBcDeF123
version_id:
type: string
nullable: true
description: ID of this specific artifact version.
example: ver_xYz9012
major_version:
type: integer
nullable: true
example: 2
agent_id:
type: string
nullable: true
description: ID of the agent that produced the artifact.
example: abc123DEFghiJKL
session_id:
type: string
nullable: true
description: ID of the session in which the artifact was produced.
example: ses_8h2k4m1n
filename:
type: string
nullable: true
example: q4_sales_report.pdf
created_at:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp of when the artifact version was created.
example: '2026-05-15T14:32:00Z'
metadata:
type: object
description: Arbitrary metadata stored with the artifact version.
url:
type: string
nullable: true
description: Signed URL for direct access to the artifact file.
example: https://storage.googleapis.com/...
creator:
type: object
nullable: true
description: The user who created this artifact version. `null` when unknown.
properties:
id:
type: string
nullable: true
example: user_19a3bc
first_name:
type: string
nullable: true
example: Ada
last_name:
type: string
nullable: true
example: Lovelace
email:
type: string
nullable: true
example: ada@example.com
profile_picture:
type: string
nullable: true
example: https://example.com/avatars/ada.png
next_cursor:
type: string
nullable: true
description: Cursor to pass as `cursor` on the next request. `null` when there are no more results.
examples:
multiple:
summary: Multiple artifacts
value:
artifacts:
- id: art_aBcDeF123
version_id: ver_xYz9012
major_version: 2
agent_id: abc123DEFghiJKL
session_id: ses_8h2k4m1n
filename: q4_sales_report.pdf
created_at: '2026-05-15T14:32:00Z'
metadata:
media_type: application/pdf
size: 12345
url: https://storage.googleapis.com/gumloop-artifacts/art_aBcDeF123?X-Goog-Signature=...
creator:
id: user_19a3bc
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: https://example.com/avatars/ada.png
- id: art_gHiJkL456
version_id: ver_aBc4567
major_version: 1
agent_id: abc123DEFghiJKL
session_id: ses_8h2k4m1n
filename: summary.txt
created_at: '2026-05-15T14:30:11Z'
metadata: {}
url: https://storage.googleapis.com/gumloop-artifacts/art_gHiJkL456?X-Goog-Signature=...
creator:
id: user_19a3bc
first_name: Ada
last_name: Lovelace
email: ada@example.com
profile_picture: null
next_cursor: eyJjcmVhdGVkX3RzIjoiMjAyNi0wNS0xNVQxNDozMDoxMVoifQ==
empty:
summary: No artifacts
value:
artifacts: []
next_cursor: null
'400':
description: Bad request — `page_size` is not an integer.
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — the caller does not have read access on the agent.
'404':
description: Agent not found.
'500':
description: Internal server error.
security:
- bearerAuth: []
/artifacts/{artifact_id}/download:
get:
summary: Download artifact
description: Returns a signed download URL for an artifact, plus its filename, media type, and size. Follow `download_url` to fetch the file bytes.
operationId: downloadArtifact
tags:
- Artifacts
x-codeSamples:
- lang: bash
label: cURL
source: "curl 'https://api.gumloop.com/api/v1/artifacts/ARTIFACT_ID/download' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n"
- lang: python
label: Python
source: 'from gumloop import Gumloop
client = Gumloop(access_token="YOUR_ACCESS_TOKEN")
response = client.artifacts.download(artifact_id="ARTIFACT_ID")
print(response.download_url, response.filename, response.size)
'
parameters:
- in: path
name: artifact_id
required: true
schema:
type: string
description: ID of the artifact to download.
- in: query
name: version_id
required: false
schema:
type: string
description: Specific version of the artifact to download. Defaults to the latest version when omitted.
responses:
'200':
description: Signed download URL and file metadata.
content:
application/json:
schema:
type: object
properties:
download_url:
type: string
description: Signed URL the caller can `GET` to fetch the file bytes.
example: https://storage.googleapis.com/gumloop-artifacts/art_aBcDeF123?X-Goog-Signature=...
filename:
type: string
nullable: true
example: q4_sales_report.pdf
media_type:
type: string
nullable: true
example: application/pdf
size:
type: integer
nullable: true
description: File size in bytes.
example: 12345
required:
- download_url
examples:
pdf:
summary: PDF artifact
value:
download_url: https://storage.googleapis.com/gumloop-artifacts/art_aBcDeF123?X-Goog-Signature=...
filename: q4_sales_report.pdf
media_type: application/pdf
size: 12345
'401':
description: Unauthorized — missing or invalid API key.
'403':
description: Forbidden — the caller does not have read access on the artifact.
'404':
description: Artifact not found, version not found, or the underlying file is unavailable.
'502':
description: Failed to generate a download URL for the underlying file.
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A personal API key or an [OAuth 2.0](/api-reference/oauth) access token. Personal API keys also require the `x-auth-key` header with your user ID.