API Reference

Base URL

https://agentgif.com/api/v1/

All endpoints are relative to this base URL. HTTPS is required — HTTP requests are redirected.

Authentication

Read endpoints (GET) are open and free — no authentication required. Write endpoints (POST, PATCH, DELETE) require an API key passed via the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://agentgif.com/api/v1/gifs/upload/ \
  -F "[email protected]" -F "title=Demo"

Get your API key at Settings → API Key. You can reset it at any time via the settings page or the /api/v1/users/me/api-key/reset/ endpoint.

Response Format

All responses are application/json. Dates use ISO 8601 format. GIF IDs are 8-character nanoid strings (e.g., xK9mQ2pL).

A typical GIF object looks like:

{
  "id": "xK9mQ2pL",
  "title": "Git Interactive Rebase",
  "slug": "git-rebase",
  "command": "git rebase -i HEAD~3",
  "shell": "zsh",
  "description": "Interactive rebase to squash commits",
  "gif_url": "https://media.agentgif.com/xK9mQ2pL.gif",
  "mp4_url": "https://media.agentgif.com/xK9mQ2pL.mp4",
  "cast_url": "https://media.agentgif.com/xK9mQ2pL.cast",
  "thumbnail_url": "https://media.agentgif.com/xK9mQ2pL_thumb.png",
  "width": 1000,
  "height": 580,
  "frames": 142,
  "duration_ms": 8500,
  "file_size_bytes": 245760,
  "visibility": "public",
  "view_count": 1234,
  "tags": ["git", "rebase", "version-control"],
  "user": {"username": "agentgif"},
  "tool": {"name": "git", "slug": "git"},
  "theme": {"name": "Catppuccin Mocha", "slug": "catppuccin-mocha"},
  "created_at": "2026-03-15T10:30:00Z",
  "detail_url": "https://agentgif.com/@agentgif/git-rebase/",
  "embed_codes": {
    "markdown": "[![Git Rebase](https://media.agentgif.com/xK9mQ2pL.gif)](https://agentgif.com/xK9mQ2pL)",
    "html": "<a href=\"https://agentgif.com/xK9mQ2pL\"><img src=\"...\" /></a>"
  }
}

Pagination

List endpoints return paginated results. Use page and page_size query parameters:

GET /api/v1/gifs/?page=2&page_size=20

Response includes pagination metadata:

{
  "count": 886,
  "next": "https://agentgif.com/api/v1/gifs/?page=3",
  "previous": "https://agentgif.com/api/v1/gifs/?page=1",
  "results": [...]
}

Default page size is 20. Maximum is 100.

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GIFs

List GIFs

GET /api/v1/gifs/

Returns all public, non-deleted GIFs ordered by creation date (newest first).

Query parameters: page, page_size, tag, shell, user.

curl -s https://agentgif.com/api/v1/gifs/?tag=docker&page_size=5 | jq '.count'

GIF Detail

GET /api/v1/gifs/{id}/

Full metadata for a single GIF including embed codes, download URLs, and file dimensions.

curl -s https://agentgif.com/api/v1/gifs/xK9mQ2pL/ | jq '.title, .gif_url'

Cast Data

GET /api/v1/gifs/{id}/cast/

Returns the raw asciinema v2 cast file — a JSON header line followed by newline-delimited event tuples [timestamp, event_type, data]. This is the machine-readable layer that AI agents use to understand the terminal session.

Transcript

GET /api/v1/gifs/{id}/transcript/

Plain text transcript of the terminal session — commands and their output, stripped of ANSI escape codes. Useful for full-text search and LLM context.

Featured GIFs

GET /api/v1/featured/

Curated selection of high-quality GIFs, hand-picked by the AgentGIF team.

Upload (Auth Required)

POST /api/v1/gifs/upload/

Upload a GIF with metadata. Accepts multipart/form-data.

curl -X POST https://agentgif.com/api/v1/gifs/upload/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "title=Docker Compose Up" \
  -F "command=docker compose up -d" \
  -F "tags=docker,compose,containers" \
  -F "[email protected]"

Update GIF (Auth Required)

PATCH /api/v1/gifs/{id}/edit/

Update title, description, tags, or visibility. Only the GIF owner can edit.

Delete GIF (Auth Required)

DELETE /api/v1/gifs/{id}/delete/

Soft-deletes the GIF. It can be recovered within 30 days.

Search

GET /api/v1/search/?q={query}

Full-text search across GIF titles, descriptions, commands, tags, and transcripts. Minimum 2 characters.

curl -s "https://agentgif.com/api/v1/search/?q=git+rebase&sort=views" | jq '.results[0].title'

Tags

List Tags

GET /api/v1/tags/

All tags with GIF counts, ordered by popularity.

GIFs by Tag

GET /api/v1/tags/{slug}/gifs/

Paginated list of GIFs with a specific tag.

curl -s https://agentgif.com/api/v1/tags/docker/gifs/ | jq '.count'

Collections

List Collections

GET /api/v1/collections/

Featured Collections

GET /api/v1/collections/featured/

Collection Detail

GET /api/v1/collections/{slug}/

Returns collection metadata and its ordered list of GIFs.

Create Collection (Auth Required)

POST /api/v1/collections/create/

Manage Collection GIFs (Auth Required)

Users

User Profile

GET /api/v1/users/{username}/

User's GIFs

GET /api/v1/users/{username}/gifs/

Authenticated User

GET /api/v1/users/me/

Returns your profile, including API key and upload stats. Requires authentication.

Reset API Key

POST /api/v1/users/me/api-key/reset/

Generates a new API key. The old key is immediately invalidated.

Themes

List Themes

GET /api/v1/themes/

All 15 terminal themes with their color palettes (foreground, background, ANSI colors).

Theme Detail

GET /api/v1/themes/{slug}/

Full color palette for a specific theme. Use this to render cast files with correct colors.

Badge Service

Terminal-themed package badges — a developer-friendly alternative to shields.io. See the Badge Playground for a visual builder.

Customize with query parameters: ?theme=dracula, ?style=flat.

<img src="https://agentgif.com/badge/pypi/requests/version.svg?theme=catppuccin-mocha" />

AI Tape Generator

Generate VHS tape scripts from natural language descriptions using AI.

Create Generation Job

POST /api/v1/gifs/generate/

Starts an async generation job. Returns a job_id to poll for status.

Check Generation Status

GET /api/v1/gifs/generate/{job_id}/

Returns the generation status (pending, processing, completed, failed) and the generated tape script when complete.

Error Codes

Error responses include a detail field with a human-readable message:

{
  "detail": "Authentication credentials were not provided."
}

OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

https://agentgif.com/api/openapi.json

Import it into Swagger UI, Insomnia, or any OpenAPI-compatible tool.