{
  "openapi": "3.1.0",
  "info": {
    "title": "ShippedByAgents read API",
    "version": "0.1.0",
    "description": "Public, read-only access to sourced stories of AI coding agents shipping software. No API key.\n\nEvery story request must declare who is calling: send X-Identity (or From) with a contact email or http(s) URL, and a User-Agent naming your client.\n\nRate limits: 30 requests per 60 seconds and 500 per 24 hours per declared identity, and 60 per 60 seconds per client IP. Over a limit you get 429 with Retry-After (seconds).\n\nEvery response carries this notice: \"Figures are per-story quotes from public sources. They are not comparable, and this API does not return an industry-average productivity gain.\" Do not average, sum or compare figures across stories as if they were measured the same way. The API never returns averages, medians or rolled-up productivity gains.\n\nduration_days, cost_usd and prs_merged are null unless the source stated a clear number. Prose numbers are in key_numbers. Full dump: /stories.json.\n\nData is free to use and quote with a link to https://www.shippedbyagents.dev."
  },
  "servers": [
    {
      "url": "https://www.shippedbyagents.dev"
    }
  ],
  "paths": {
    "/api/stories": {
      "get": {
        "operationId": "search_stories",
        "summary": "Filter stories (exact match, all filters AND together)",
        "description": "Sorted by source publish date (newest first, undated last), then date accessed. Returns at most 25. Unknown parameters, repeated parameters and query strings over 300 characters are rejected with 400.",
        "parameters": [
          {
            "name": "X-Identity",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Required unless From is sent. A contact email or http(s) URL for whoever runs the client, e.g. https://example.com/my-agent. Not a secret, nothing is issued."
          },
          {
            "name": "From",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Fallback for X-Identity (standard HTTP From header). Same rules."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8
            },
            "description": "Names your client, e.g. my-research-agent/1.0. At least 8 characters."
          },
          {
            "name": "work_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Language port",
                "Migration",
                "Test migration",
                "Upgrade / modernisation",
                "Refactor / maintenance",
                "Feature",
                "New product",
                "Company rollout",
                "Research / benchmark"
              ]
            },
            "description": "Kind of work."
          },
          {
            "name": "codebase",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "greenfield",
                "brownfield",
                "mixed",
                "n/a"
              ]
            },
            "description": "Existing code (brownfield), new code (greenfield), both, or not applicable."
          },
          {
            "name": "tool",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Claude Code",
                "Claude",
                "Claude Agent SDK",
                "OpenAI Codex",
                "Cursor",
                "GitHub Copilot",
                "Devin",
                "Amazon Q Developer",
                "Gemini CLI",
                "Sourcegraph Cody",
                "Factory Droid",
                "Amp",
                "AICode",
                "Google Antigravity",
                "Lovable",
                "Mistral Vibe",
                "Grok CLI",
                "Jules",
                "OpenCode",
                "Niteshift",
                "Goose",
                "Rovo Dev",
                "Unstated",
                "claude-code",
                "claude",
                "claude-agent-sdk",
                "codex",
                "cursor",
                "github-copilot",
                "devin",
                "amazon-q-developer",
                "gemini-cli",
                "sourcegraph-cody",
                "factory-droid",
                "amp",
                "aicode",
                "google-antigravity",
                "lovable",
                "mistral-vibe",
                "grok-cli",
                "jules",
                "opencode",
                "niteshift",
                "goose",
                "rovo-dev",
                "unstated"
              ]
            },
            "description": "Catalogue tool name or its slug, e.g. \"Claude Code\" or \"claude-code\". Unstated means the source named no tool."
          },
          {
            "name": "source_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "vendor",
                "builder",
                "independent"
              ]
            },
            "description": "Who published the source: vendor (tool maker), builder (the team that did the work) or independent."
          },
          {
            "name": "has_cost",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Only stories where cost_usd is (true) or is not (false) stated."
          },
          {
            "name": "has_duration",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Only stories where duration_days is (true) or is not (false) stated."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            },
            "description": "Max stories returned. Values over 25 are capped at 25."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching stories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoryList"
                }
              }
            }
          },
          "400": {
            "description": "Bad query or missing/invalid identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET is allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/stories/{slug}": {
      "get": {
        "operationId": "get_story",
        "summary": "One story by slug",
        "parameters": [
          {
            "name": "X-Identity",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Required unless From is sent. A contact email or http(s) URL for whoever runs the client, e.g. https://example.com/my-agent. Not a secret, nothing is issued."
          },
          {
            "name": "From",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Fallback for X-Identity (standard HTTP From header). Same rules."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8
            },
            "description": "Names your client, e.g. my-research-agent/1.0. At least 8 characters."
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The story",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoryItem"
                }
              }
            }
          },
          "400": {
            "description": "Bad slug format or missing/invalid identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such story",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET is allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "operationId": "openapi",
        "summary": "This document. No identity needed (still IP rate limited).",
        "responses": {
          "200": {
            "description": "OpenAPI document"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Notice": {
        "type": "string",
        "const": "Figures are per-story quotes from public sources. They are not comparable, and this API does not return an industry-average productivity gain."
      },
      "StoryList": {
        "type": "object",
        "required": [
          "notice",
          "count",
          "total",
          "stories"
        ],
        "properties": {
          "notice": {
            "$ref": "#/components/schemas/Notice"
          },
          "count": {
            "type": "integer",
            "description": "Stories in this response"
          },
          "total": {
            "type": "integer",
            "description": "Matching stories before limit"
          },
          "stories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Story"
            }
          }
        }
      },
      "StoryItem": {
        "type": "object",
        "required": [
          "notice",
          "story"
        ],
        "properties": {
          "notice": {
            "$ref": "#/components/schemas/Notice"
          },
          "story": {
            "$ref": "#/components/schemas/Story"
          }
        }
      },
      "Story": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "source_name": {
            "type": "string"
          },
          "source_type": {
            "type": "string",
            "enum": [
              "vendor",
              "builder",
              "independent"
            ]
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Source publish date (YYYY, YYYY-MM or YYYY-MM-DD), not the date we added the story; null if the source gave none. Newest-first ordering uses this date."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "work_type": {
            "type": "string",
            "enum": [
              "Language port",
              "Migration",
              "Test migration",
              "Upgrade / modernisation",
              "Refactor / maintenance",
              "Feature",
              "New product",
              "Company rollout",
              "Research / benchmark"
            ]
          },
          "codebase": {
            "type": "string",
            "enum": [
              "greenfield",
              "brownfield",
              "mixed",
              "n/a"
            ]
          },
          "key_numbers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            },
            "description": "Numbers as quoted from the source, in prose."
          },
          "duration_days": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Calendar or wall-clock duration of the work in days, as stated by the source, including sourced estimates of a clear number. Weeks x 7; hours / 24 (3 decimals). Null for months, ranges, bounds (\"under\", \"over\"), effort or working days."
          },
          "cost_usd": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Money the team stated it spent on tokens/API/model/tools/infra for the work, including sourced estimates of that spend. Null for savings, unit prices, ranges, run rates, subscription prices, and API-price equivalents the source says were not paid."
          },
          "prs_merged": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Total pull/merge requests merged for the work, as stated. Null for rates, shares and floors (\"1,500+\")."
          },
          "claimed_benefits": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "techniques": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "caveats": {
            "type": "string"
          },
          "updated": {
            "type": [
              "string",
              "null"
            ]
          },
          "update_note": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}