{ "openapi": "3.1.0", "info": { "title": "abliteration.org Public API", "version": "1.0.0", "description": "Read access to the abliteration.org catalog: models and their method classification, alignment datasets and their passports, the M-code taxonomy, the four flagship indices and the curated field timeline.\n\nEvery call is authenticated with a bearer key and metered in credits against the same wallet the Research Agent spends from. There is no free tier for machine traffic and no separate billing.\n\nResponses report `cost` and `credits_remaining` on every success. While `metering` reads `preview`, the cost shown is what the call will bill once metering is enabled and nothing is actually deducted; when it reads `billed`, it was.", "contact": { "url": "https://abliteration.org/api" } }, "servers": [ { "url": "https://abliteration.org" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "models", "description": "Abliterated and uncensored models." }, { "name": "methods", "description": "The M-code classification taxonomy." }, { "name": "indices", "description": "The four flagship indices." }, { "name": "authors", "description": "Model publishers, aggregated." }, { "name": "datasets", "description": "Alignment datasets and passports." }, { "name": "timeline", "description": "Curated events in the field." } ], "paths": { "/api/v1/models": { "get": { "tags": [ "models" ], "operationId": "listModels", "summary": "List models", "description": "Cost: 5-300+ credits, stepped by returned rows and multiplied by `1 + (offset/2500)²`. A filtered lookup up to 200 rows costs 5; a 1000-row page on the first page costs 300; on offset=10000, 5100. Filter cheap, dump expensive. See /api#pricing. Delisted models are excluded by default (`delisted=live`); pass `delisted=dead|all` to include tombstoned records. A dedicated change-stream endpoint is at GET /api/v1/models/delisted.", "parameters": [ { "name": "method", "in": "query", "description": "M-code, case-insensitive. See GET /api/v1/methods.", "schema": { "type": "string" } }, { "name": "family", "in": "query", "description": "Base family, for example qwen or llama.", "schema": { "type": "string" } }, { "name": "author", "in": "query", "description": "Publisher handle, case-insensitive.", "schema": { "type": "string" } }, { "name": "license", "in": "query", "description": "SPDX-ish license string as published.", "schema": { "type": "string" } }, { "name": "downloads_gte", "in": "query", "schema": { "type": "integer" } }, { "name": "downloads_lte", "in": "query", "schema": { "type": "integer" } }, { "name": "created_after", "in": "query", "description": "ISO-8601 date or timestamp, inclusive.", "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "description": "ISO-8601 date or timestamp, inclusive.", "schema": { "type": "string" } }, { "name": "delisted", "in": "query", "description": "Tombstone filter. `live` (default): HF-visible models only. `dead`: delisted-only (same shape as this endpoint plus is_delisted=1 and last_seen_at). `all`: both, in one page. For a purpose-built change-stream feed, prefer GET /api/v1/models/delisted.", "schema": { "type": "string", "enum": [ "live", "dead", "all" ], "default": "live" } }, { "name": "sort", "in": "query", "description": "Bare key is the natural direction (downloads/likes = most first, dates = newest first). A leading `-` flips it. `created` and `first_seen` are aliases for the full column names.", "schema": { "type": "string", "enum": [ "downloads", "-downloads", "likes", "-likes", "created", "-created", "created_at", "-created_at", "first_seen", "-first_seen", "first_seen_at", "-first_seen_at" ], "default": "downloads" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Matching models.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/historical-deletions/summary": { "get": { "tags": [ "models" ], "operationId": "getHistoricalDeletionSummary", "summary": "Historical deletions — aggregate summary", "description": "Cost: 20 credits, flat. Aggregates from the 24-month HF snapshot analysis: total ever seen, total deleted, deletion rate, average months alive, monthly timeline of losses, top-10 by peak downloads. One call replaces half a dozen separate queries.", "responses": { "200": { "description": "Deletion summary.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeletionSummary" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/historical-deletions/list": { "get": { "tags": [ "models" ], "operationId": "listHistoricalDeletions", "summary": "Historical deletions — paged list", "description": "Cost: 5 credits, flat. Paged/filterable window on the 24-month deletion backlog. Rows are frozen at the moment the model was last seen on the Hub — peak_downloads and total_months_alive never change after death. Sort by size (`downloads`, default), recency (`recent`, newest deaths first) or lifespan (`lifespan`, longest-lived first — surprising deaths).", "parameters": [ { "name": "since_month", "in": "query", "description": "ISO YYYY-MM. Rows with last_seen_month >= it only.", "schema": { "type": "string" } }, { "name": "min_peak_downloads", "in": "query", "description": "Only rows whose peak downloads >= this. `casualties over N` queries.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "`downloads` (default, biggest first), `recent` (newest last_seen_month first), `lifespan` (longest-lived first).", "schema": { "type": "string", "enum": [ "downloads", "recent", "lifespan" ], "default": "downloads" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Historical deletions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalDeletion" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/delisted": { "get": { "tags": [ "models" ], "operationId": "listDelistedModels", "summary": "List delisted models (change stream)", "description": "Cost: 5 credits, flat. Change-stream companion to /models: every row is a tombstone — a model that HF no longer serves, preserved here at its final state. Poll with `since=` to fetch only new casualties; callers building compliance dashboards, safety-research corpora, or \"wayback\" tools live on this endpoint. See /api#change-stream.", "parameters": [ { "name": "since", "in": "query", "description": "ISO-8601 date or timestamp. Rows with last_seen_at >= since only. Use your previous poll's newest last_seen_at to build an incremental feed.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "`recent` (default, newest disappearance first) or `downloads` (biggest casualties first — best for post-mortem coverage).", "schema": { "type": "string", "enum": [ "recent", "downloads" ], "default": "recent" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Delisted models.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DelistedModel" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/market/anomalies": { "get": { "tags": [ "models" ], "operationId": "listAnomalies", "summary": "Anomalies in the download counter (change stream)", "description": "Cost: 15 credits, flat. Every row is a model whose downloads-per-window has crossed a threshold: 2× jump = `spike`, 0.5× fall = `drop`. Sorted by absolute delta so biggest movers surface first. Consumers get \"what is happening in the field right now\" without re-implementing the ETL over `download_history`.", "parameters": [ { "name": "window_days", "in": "query", "description": "Baseline distance in days. Default 7, min 1, max 365.", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 7 } }, { "name": "min_baseline", "in": "query", "description": "Only rows where baseline downloads >= this. Filters `0→10` noise. Default 1000.", "schema": { "type": "integer", "minimum": 1, "default": 1000 } }, { "name": "kind", "in": "query", "description": "Filter to one class. Omit for both.", "schema": { "type": "string", "enum": [ "spike", "drop" ] } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Detected anomalies.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadAnomaly" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{id}/download-history": { "get": { "tags": [ "models" ], "operationId": "getModelDownloadHistory", "summary": "Per-model download timeline", "description": "Cost: 5 credits, flat. Raw signal that /market/anomalies scans over. Callers with a chart or their own anomaly detector pull it once per model.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "description": "Window in days (max 365). Pass 0 for full history.", "schema": { "type": "integer", "minimum": 0, "maximum": 365, "default": 90 } } ], "responses": { "200": { "description": "Timeline.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadPoint" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{id}/drifts": { "get": { "tags": [ "models" ], "operationId": "listModelReadmeDrifts", "summary": "README drift stream for one model", "description": "Cost: 5 credits, flat. Every commit that changed the model's README on HF, with `size_delta` between commits so a consumer spots growth spurts and hard prunes without fetching each version. Poll with `since_ts=` for an incremental drift feed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mlabonne/Qwen3-30B-A3B-abliterated" }, { "name": "since_ts", "in": "query", "description": "Unix epoch seconds. Rows with commit_ts >= it only.", "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "README commits.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReadmeDrift" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{id}/readme-at/{commit}": { "get": { "tags": [ "models" ], "operationId": "getModelReadmeAt", "summary": "README content at one commit (wayback)", "description": "Cost: 10 credits, flat. The wayback-machine leg of the change-stream. Returns the exact README content for one model at one commit sha — used after spotting a suspicious drift on GET /api/v1/models/{id}/drifts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commit", "in": "path", "required": true, "schema": { "type": "string" }, "description": "HF commit sha for the README, from /drifts." } ], "responses": { "200": { "description": "README content at commit.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReadmeAt" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{id}": { "get": { "tags": [ "models" ], "operationId": "getModel", "summary": "Get one model", "description": "Cost: 10 credits. Priced above /authors/[id], /methods/[id] and /datasets/[id] because iterating over model ids is functionally a slow dump. The id is author/name and must be percent-encoded. Delisted models are served here even though they are hidden from the default catalog list; the response then carries `is_delisted=1` and `days_since_gone`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mlabonne/Qwen3-30B-A3B-abliterated" } ], "responses": { "200": { "description": "Full model record.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ModelDetail" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/methods": { "get": { "tags": [ "methods" ], "operationId": "listMethods", "summary": "List the method taxonomy", "description": "Cost: 5-15 credits. Every code is returned, including ones with no models.", "responses": { "200": { "description": "The taxonomy with counts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Method" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/methods/{id}": { "get": { "tags": [ "methods" ], "operationId": "getMethod", "summary": "Get one method", "description": "Cost: 1 credit.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "M1", "M2", "M3", "M4", "M5", "M5-frankenstein", "M6", "M7", "M8", "M-uncensored", "unknown" ] } } ], "responses": { "200": { "description": "Method with counts, top authors and sample models.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MethodDetail" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/indices": { "get": { "tags": [ "indices" ], "operationId": "listIndices", "summary": "All four indices", "description": "Cost: 20 credits. Check the measured flag before treating a value as a finding.", "responses": { "200": { "description": "Current values with recent DAI history.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Index" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/indices/{id}": { "get": { "tags": [ "indices" ], "operationId": "getIndex", "summary": "One index with history", "description": "Cost: 10 credits. Only dai has a history series; the others return an empty array with history_available false.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "dai", "DAI", "freedom-velocity", "FV", "freedom_velocity", "weaponization", "WEAP", "f2w-latency", "F2W", "f2w_latency" ] }, "description": "Canonical id or one of the short aliases (DAI, FV, WEAP, F2W). Case-insensitive." } ], "responses": { "200": { "description": "Index with its full series.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IndexDetail" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/authors": { "get": { "tags": [ "authors" ], "operationId": "listAuthors", "summary": "List authors", "description": "Cost: 5-15 credits, by rows returned.", "parameters": [ { "name": "sort", "in": "query", "description": "Bare key is DESC (largest first); a leading `-` flips to ASC. Aliases: `downloads` == `total_downloads`, `models` == `total_models`, `likes` == `total_likes`.", "schema": { "type": "string", "enum": [ "total_downloads", "-total_downloads", "downloads", "-downloads", "total_models", "-total_models", "models", "-models", "total_likes", "-total_likes", "likes", "-likes" ], "default": "total_downloads" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Authors with aggregate totals.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/authors/{id}": { "get": { "tags": [ "authors" ], "operationId": "getAuthor", "summary": "Get one author", "description": "Cost: 1 credit.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mlabonne" } ], "responses": { "200": { "description": "Author totals plus their top models.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthorDetail" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/datasets": { "get": { "tags": [ "datasets" ], "operationId": "listDatasets", "summary": "List datasets", "description": "Cost: 5-15 credits, by rows returned.", "parameters": [ { "name": "category", "in": "query", "description": "Workflow stage, for example heal or extract.", "schema": { "type": "string" } }, { "name": "author", "in": "query", "description": "Publisher handle, case-insensitive.", "schema": { "type": "string" } }, { "name": "license", "in": "query", "description": "License string as published.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Bare key is the natural direction (downloads/likes = most first, dates = newest first). A leading `-` flips it. `created` and `first_seen` are aliases for the full column names.", "schema": { "type": "string", "enum": [ "downloads", "-downloads", "likes", "-likes", "created", "-created", "created_at", "-created_at", "first_seen", "-first_seen", "first_seen_at", "-first_seen_at" ], "default": "downloads" } }, { "name": "limit", "in": "query", "description": "Rows to return, 1 to 1000. Values outside the range are clamped, not rejected.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "offset", "in": "query", "description": "Rows to skip. Negative and non-numeric values are treated as 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Matching datasets.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/datasets/{id}": { "get": { "tags": [ "datasets" ], "operationId": "getDataset", "summary": "Get one dataset", "description": "Cost: 1 credit. The passport is null for datasets that do not have one yet.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mlabonne/orpo-dpo-mix-40k" } ], "responses": { "200": { "description": "Dataset with files and passport.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DatasetDetail" } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/timeline": { "get": { "tags": [ "timeline" ], "operationId": "listTimeline", "summary": "Curated field events", "description": "Cost: 50 credits, flat.", "parameters": [ { "name": "from", "in": "query", "description": "Inclusive lower bound on the event date, ISO-8601.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on the event date, ISO-8601.", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "description": "Event type, case-insensitive.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "Events, newest first.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Only possible while metering is enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-key rate limit exceeded. Retry-After header is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unreadable. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A key issued at /shop/account#api-keys. Send it as: Authorization: Bearer abl_live_..." } }, "schemas": { "Envelope": { "type": "object", "required": [ "data", "cost", "credits_remaining", "rate_limit_limit", "rate_limit_remaining", "rate_limit_reset", "metering", "request_id" ], "properties": { "data": { "description": "The payload. An array on list routes, an object on single-entity routes." }, "cost": { "type": "integer", "description": "Credits this call costs." }, "credits_remaining": { "type": "integer", "description": "Wallet balance after the call. Unchanged while metering is preview." }, "rate_limit_limit": { "type": "integer", "description": "Ceiling for the current window. Also returned as X-RateLimit-Limit." }, "rate_limit_remaining": { "type": "integer", "description": "Calls left in the current window for this key. Also returned as X-RateLimit-Remaining." }, "rate_limit_reset": { "type": "integer", "description": "Unix seconds at which the window resets to full ceiling. Also returned as X-RateLimit-Reset." }, "metering": { "type": "string", "enum": [ "preview", "billed" ], "description": "Whether cost was actually deducted." }, "request_id": { "type": "string", "format": "uuid", "description": "Also returned in the x-request-id header." } } }, "Error": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable slug." }, "message": { "type": "string", "description": "Human-readable detail. May be reworded at any time." }, "retry_after": { "type": "integer", "description": "Seconds to wait. Present on 429." }, "credits_remaining": { "type": "integer", "description": "Present on 402." }, "request_id": { "type": "string", "format": "uuid" } } }, "ModelSummary": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "type": "string" }, "name": { "type": "string" }, "method": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] }, "params_b": { "type": [ "number", "null" ] }, "license": { "type": [ "string", "null" ] }, "downloads": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "is_gguf": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "first_seen_at": { "type": [ "string", "null" ] }, "is_delisted": { "type": [ "integer", "null" ], "description": "0/1 flag, present in every response row. `1` means the model is no longer on the Hub." }, "last_seen_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the last successful Hub observation. Non-null on delisted rows." } } }, "DownloadAnomaly": { "type": "object", "description": "One model whose downloads-per-window crossed a threshold.", "properties": { "model_id": { "type": "string" }, "current_at": { "type": "string", "description": "ISO-8601 timestamp of the current snapshot." }, "current_downloads": { "type": "integer", "format": "int64" }, "baseline_at": { "type": "string", "description": "ISO-8601 timestamp of the baseline snapshot the delta is computed against." }, "baseline_downloads": { "type": "integer", "format": "int64" }, "ratio": { "type": "number", "description": "current_downloads / baseline_downloads." }, "delta": { "type": "integer", "format": "int64", "description": "current_downloads - baseline_downloads (signed)." }, "kind": { "type": "string", "enum": [ "spike", "drop" ], "description": "`spike` when ratio >= 2, `drop` when ratio <= 0.5." } } }, "DownloadPoint": { "type": "object", "description": "One snapshot in a per-model download timeline.", "properties": { "date": { "type": "string", "description": "ISO-8601 timestamp of the observation." }, "downloads": { "type": "integer", "format": "int64" } } }, "ReadmeDrift": { "type": "object", "description": "One commit that changed the model's README on HF.", "properties": { "commit_sha": { "type": "string" }, "commit_ts": { "type": "integer", "format": "int64", "description": "Unix epoch seconds." }, "commit_message": { "type": [ "string", "null" ] }, "content_size": { "type": "integer", "description": "README byte size at this commit." }, "size_delta": { "type": "integer", "description": "Bytes added (positive) or removed (negative) since the previous commit. First commit gets 0." } } }, "ReadmeAt": { "type": "object", "description": "Wayback-machine view: full README content at one commit.", "properties": { "id": { "type": "string", "description": "Model id (author/name)." }, "commit": { "type": "string", "description": "Commit sha (echoes the path param)." }, "content": { "type": "string", "description": "Full README markdown at that commit. Up to ~100KB." } } }, "HistoricalDeletion": { "type": "object", "properties": { "id": { "type": "string" }, "first_seen_month": { "type": "string", "description": "ISO YYYY-MM of the earliest snapshot the model appears in." }, "last_seen_month": { "type": "string", "description": "ISO YYYY-MM of the final snapshot before deletion." }, "total_months_alive": { "type": "integer", "description": "Whole months between first and last observation." }, "peak_downloads": { "type": "integer", "format": "int64", "description": "Highest downloads count observed during the model's lifetime." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp the model was originally created on HF (from the frozen snapshot)." } } }, "DeletionSummary": { "type": "object", "description": "Aggregate rollup of the 24-month HF deletion analysis.", "properties": { "total_ever_seen": { "type": "integer", "description": "Live catalog size plus historical deletions." }, "total_deleted": { "type": "integer" }, "deletion_rate_pct": { "type": "number", "description": "Percentage of ever-seen models that are now gone." }, "avg_months_alive": { "type": "number", "description": "Average lifespan of deleted models, in months." }, "timeline": { "type": "array", "description": "Deletions grouped by last_seen_month, ascending.", "items": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer" } } } }, "top_by_downloads": { "type": "array", "description": "Top-10 biggest casualties by peak downloads.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peak_downloads": { "type": "integer", "format": "int64" }, "last_seen_month": { "type": "string" }, "months_alive": { "type": "integer" } } } } } }, "DelistedModel": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "type": "string" }, "family": { "type": [ "string", "null" ] }, "params_b": { "type": [ "number", "null" ] }, "downloads": { "type": "integer", "description": "Downloads at the moment the model was last visible on HF. Not a live counter.", "format": "int64" }, "last_seen_at": { "type": "string", "description": "ISO-8601 timestamp of the last successful Hub observation. Approximately when the model died." }, "days_since_gone": { "type": "integer", "description": "Whole days between last_seen_at and now, computed server-side for convenience." } } }, "ModelDetail": { "type": "object", "description": "The full catalog record, plus files, benchmarks and an author summary.", "properties": { "id": { "type": "string" }, "author": { "type": "string" }, "name": { "type": "string" }, "primary_method": { "type": [ "string", "null" ] }, "secondary_methods": { "type": [ "string", "null" ], "description": "JSON-encoded array of extra method codes." }, "confidence": { "type": [ "string", "null" ] }, "classification_evidence": { "type": [ "string", "null" ], "description": "JSON-encoded array of evidence strings." }, "classifier_version": { "type": [ "string", "null" ] }, "classified_at": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] }, "params_b": { "type": [ "number", "null" ] }, "is_gguf": { "type": [ "integer", "null" ] }, "is_moe": { "type": [ "integer", "null" ] }, "is_multimodal": { "type": [ "integer", "null" ] }, "is_image_gen": { "type": [ "integer", "null" ] }, "is_second_order": { "type": [ "integer", "null" ] }, "downloads": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "last_modified": { "type": [ "string", "null" ] }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "is_delisted": { "type": [ "integer", "null" ], "description": "0/1 flag. `1` means HF no longer serves this model — the response is the last state we recorded." }, "days_since_gone": { "type": [ "integer", "null" ], "description": "Whole days between last_seen_at and now. `null` unless is_delisted=1." }, "readme_text": { "type": [ "string", "null" ] }, "readme_status": { "type": [ "string", "null" ] }, "tags": { "type": [ "string", "null" ], "description": "JSON-encoded array of Hub tags." }, "pipeline_tag": { "type": [ "string", "null" ] }, "library_name": { "type": [ "string", "null" ] }, "yaml_base_model": { "type": [ "string", "null" ] }, "yaml_language": { "type": [ "string", "null" ] }, "yaml_datasets": { "type": [ "string", "null" ] }, "yaml_license": { "type": [ "string", "null" ] }, "yaml_tags": { "type": [ "string", "null" ] }, "files_count": { "type": [ "integer", "null" ] }, "total_size_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "largest_file_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "smallest_model_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "quantizations": { "type": [ "string", "null" ], "description": "JSON-encoded array of quantisation labels." }, "has_mmproj": { "type": [ "integer", "null" ] }, "hub_downloads_all_time": { "type": [ "integer", "null" ], "format": "int64" }, "hub_trending_score": { "type": [ "integer", "null" ] }, "hub_real_params_m": { "type": [ "number", "null" ] }, "hub_context_length": { "type": [ "integer", "null" ] }, "hub_siblings_count": { "type": [ "integer", "null" ] }, "hub_provider_count": { "type": [ "integer", "null" ] }, "hub_provider_names": { "type": [ "string", "null" ] }, "hub_enriched_at": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "type": "object" }, "description": "Per-file manifest: filename, size_bytes, sha256, quantization, is_model_file, is_mmproj." }, "benchmarks": { "type": "object", "description": "Two arrays under `own` and `base` — each item has benchmark_name, score, source, pertains_to." }, "author_summary": { "anyOf": [ { "$ref": "#/components/schemas/Author" }, { "type": "null" } ] } }, "additionalProperties": true }, "Method": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "original", "repackage", "merged", "unclassified" ] }, "wiki_slug": { "type": [ "string", "null" ] }, "model_count": { "type": "integer" }, "total_downloads": { "type": "integer", "format": "int64" } } }, "MethodDetail": { "allOf": [ { "$ref": "#/components/schemas/Method" }, { "type": "object", "properties": { "wiki_url": { "type": [ "string", "null" ] }, "top_authors": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string" }, "count": { "type": "integer" } } } }, "sample_models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } } ] }, "Index": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "dai", "freedom-velocity", "weaponization", "f2w-latency" ] }, "name": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "percent", "days" ] }, "measured": { "type": "boolean", "description": "False when the value is a placeholder constant rather than a measurement." }, "source": { "type": "string", "description": "Where the number is produced." }, "history_available": { "type": "boolean" }, "as_of": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "recent_history": { "type": "array", "items": { "$ref": "#/components/schemas/DaiPoint" } } } }, "IndexDetail": { "allOf": [ { "$ref": "#/components/schemas/Index" }, { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/DaiPoint" } } } } ] }, "DaiPoint": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-09" }, "weighted_dai_pct": { "type": "number" }, "bases_included": { "type": "integer" } } }, "Author": { "type": "object", "properties": { "id": { "type": "string", "description": "Same value as `author`; added for consistency with the other single-entity payloads." }, "author": { "type": "string" }, "total_models": { "type": "integer" }, "total_downloads": { "type": "integer", "format": "int64" }, "total_likes": { "type": "integer" }, "first_seen_at": { "type": [ "string", "null" ] } } }, "AuthorDetail": { "allOf": [ { "$ref": "#/components/schemas/Author" }, { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } } } } ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "license": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "downloads": { "type": [ "integer", "null" ], "description": "Recent-window downloads reported by the Hub." }, "downloads_all": { "type": [ "integer", "null" ], "format": "int64", "description": "All-time downloads reported by the Hub." }, "likes": { "type": [ "integer", "null" ] }, "trending_score": { "type": [ "integer", "null" ] }, "gated": { "type": [ "integer", "null" ], "description": "Server returns 0/1 (SQLite bool convention), not a JSON boolean." }, "main_size_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "size_display": { "type": [ "string", "null" ], "description": "Human-formatted size (e.g. \"90.4 MB\")." }, "age_days": { "type": [ "integer", "null" ] }, "is_trending": { "type": [ "integer", "null" ], "description": "Server returns 0/1, not a JSON boolean." }, "just_added": { "type": [ "integer", "null" ], "description": "Server returns 0/1, not a JSON boolean." }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "hf_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "last_modified_at": { "type": [ "string", "null" ] }, "first_seen_at": { "type": [ "string", "null" ] } } }, "DatasetDetail": { "allOf": [ { "$ref": "#/components/schemas/Dataset" }, { "type": "object", "description": "The full dataset record, plus files and the passport when one exists.", "properties": { "files": { "type": "array", "items": { "type": "object" }, "description": "Per-file entries: path, type, size_bytes, is_lfs." }, "passport": { "anyOf": [ { "$ref": "#/components/schemas/Passport" }, { "type": "null" } ] } } } ] }, "Passport": { "type": "object", "properties": { "one_liner": { "type": "string" }, "practitioner": { "type": "string" }, "research": { "type": "string" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "date_precision": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "primary_source_url": { "type": [ "string", "null" ] } } } } } }