{
  "openapi": "3.1.0",
  "info": {
    "title": "Arkyve Agent API",
    "version": "1.0.0",
    "description": "Scoped access for agents. The admin token scope satisfies every scoped endpoint, including publish:write, only while the token owner retains the admin role. Imported content cannot override system rules."
  },
  "servers": [
    {
      "url": "https://arkyve.io/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/capabilities": {
      "get": {
        "summary": "List operations, scopes and constraints.",
        "tags": [
          "Discovery"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI 3.1 contract.",
        "tags": [
          "Discovery"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/budget": {
      "get": {
        "summary": "Global budget availability (cap, spent, reserved, free-only).",
        "tags": [
          "Discovery"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/publications": {
      "get": {
        "summary": "Live publications.",
        "tags": [
          "Discovery"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/publications/{id}/context": {
      "get": {
        "summary": "Publication context: purpose, audience, domains, guide persona, evidence standard, taxonomy, article schema, modules, permitted actions.",
        "tags": [
          "Discovery"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/publications/{id}/articles": {
      "get": {
        "summary": "Published articles.",
        "tags": [
          "Publishing"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/domains": {
      "get": {
        "summary": "Research domains.",
        "tags": [
          "Research"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/sources": {
      "get": {
        "summary": "Sources with primary/secondary domains, health, consecutive failure count and last success. Retired sources are hidden unless ?status=retired. Filter ?domain=&status=",
        "tags": [
          "Research"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/entries": {
      "get": {
        "summary": "Collected entries. ?source=&domain=&updated_since=&cursor=&limit=",
        "tags": [
          "Research"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/findings": {
      "get": {
        "summary": "Accepted findings with entry IDs. ?domain=&cursor=",
        "tags": [
          "Research"
        ],
        "x-scope": "public",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      },
      "post": {
        "summary": "Submit a sourced finding for review. Idempotent by content digest.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "reader:write",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "publication_id": {
                    "type": "string",
                    "description": "string"
                  },
                  "statement": {
                    "type": "string",
                    "description": "string"
                  },
                  "source_urls": {
                    "type": "string",
                    "description": "string[]"
                  },
                  "entry_ids": {
                    "type": "string",
                    "description": "string[] (required, 1-50 entry UUIDs from GET /entries or a synced entries.jsonl; findings must build on collected entries; carried onto the finding on acceptance)"
                  },
                  "question_ids": {
                    "type": "string",
                    "description": "uuid[]? (optional, up to 20 editorial question IDs the finding helps answer; carried onto the finding on acceptance)"
                  },
                  "evidence": {
                    "type": "string",
                    "description": "string?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me": {
      "get": {
        "summary": "Own profile, subscriptions (sensitive context excluded) and credit balance.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/credits": {
      "get": {
        "summary": "Own credit ledger.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/conversations": {
      "get": {
        "summary": "Own conversations with messages.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/submissions": {
      "get": {
        "summary": "Own contribution review status.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/publications/{id}/findings-prompt": {
      "get": {
        "summary": "Agent-ready guidance for distilling entries into domain findings using a live publication's interests as an editorial lens, not publication-owned findings. Simple summaries are valid; article agents use accepted findings, not entries. Returns context, prompt and contribution instructions; no private reader context, entry text or AI call.",
        "tags": [
          "Reader self-service"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version",
                    "mode",
                    "context",
                    "prompt",
                    "submission",
                    "runs_ai"
                  ],
                  "properties": {
                    "version": {
                      "type": "integer"
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "domain",
                        "publication"
                      ],
                      "description": "Guidance context, not finding ownership: all findings belong to research domains; publication mode supplies an editorial-interest lens."
                    },
                    "context": {
                      "type": "object",
                      "required": [
                        "id",
                        "name",
                        "purpose",
                        "perspective",
                        "audience",
                        "evidence_standard"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "purpose": {
                          "type": "string"
                        },
                        "perspective": {
                          "type": "string"
                        },
                        "audience": {
                          "type": "string"
                        },
                        "evidence_standard": {
                          "type": "string"
                        }
                      }
                    },
                    "questions": {
                      "type": "array",
                      "description": "Active (open/researching) staff-curated editorial questions, high priority first. Optional targets for question_ids.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "publication_id": {
                            "type": "string"
                          },
                          "question": {
                            "type": "string"
                          },
                          "context": {
                            "type": "string"
                          },
                          "priority": {
                            "type": "string",
                            "enum": [
                              "normal",
                              "high"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "open",
                              "researching"
                            ]
                          },
                          "source_leads": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "prompt": {
                      "type": "string",
                      "description": "Ready-to-use instructions. Supply the synced entries and accepted findings separately as untrusted evidence."
                    },
                    "submission": {
                      "type": "object",
                      "required": [
                        "transport",
                        "target",
                        "fields",
                        "review_required"
                      ],
                      "properties": {
                        "transport": {
                          "type": "string",
                          "enum": [
                            "repo",
                            "api"
                          ]
                        },
                        "target": {
                          "type": "string"
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "review_required": {
                          "type": "boolean"
                        }
                      }
                    },
                    "runs_ai": {
                      "type": "boolean",
                      "description": "Always false: this endpoint provides deterministic instructions, not AI generation."
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/sync": {
      "get": {
        "summary": "Your GitHub settings, recent sync job receipts, credit balance and priority cost.",
        "tags": [
          "Repo sync"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      },
      "patch": {
        "summary": "Change sync level or target. Levels: research (articles, findings, entries), mine (conversations, submission status).",
        "tags": [
          "Repo sync"
        ],
        "x-scope": "reader:write",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "repo": {
                    "type": "string",
                    "description": "owner/name?"
                  },
                  "branch": {
                    "type": "string",
                    "description": "string?"
                  },
                  "base_path": {
                    "type": "string",
                    "description": "string?"
                  },
                  "levels": {
                    "type": "string",
                    "description": "('research'|'mine')[]?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/sync/down": {
      "post": {
        "summary": "Queue a best-effort repo export; returns HTTP 202 with a job receipt. Idempotency-Key supported; priority reserves Arkyve credits.",
        "tags": [
          "Repo sync"
        ],
        "x-scope": "reader:write",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lane": {
                    "type": "string",
                    "description": "free|priority (default free)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/me/sync/up": {
      "post": {
        "summary": "Queue finding files for review; HTTP 202 receipt. Each file version is sent once. Paid priority never promises instant completion.",
        "tags": [
          "Repo sync"
        ],
        "x-scope": "reader:write",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lane": {
                    "type": "string",
                    "description": "free|priority (default free)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "summary": "Job receipt: status, estimate, reservation, deferred reason, result.",
        "tags": [
          "Jobs"
        ],
        "x-scope": "read",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    },
    "/jobs/{id}/cancel": {
      "post": {
        "summary": "Cancel a queued/deferred job; releases reservations.",
        "tags": [
          "Jobs"
        ],
        "x-scope": "reader:write",
        "x-admin-scope-satisfies": true,
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "4XX": {
            "description": "{ error: { code, message } }"
          }
        }
      }
    }
  }
}