Cytado API

openapi: 3.1.0
info:
  title: Cytado API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 14 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Cytado has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 7
    documentation: 7
    pages-with-code: 10
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://cytado.com/citation-api
  - https://cytado.com/evidence-api
  - https://cytado.com/bibliography-api
  - https://cytado.com/citation-verification-api
  - https://cytado.com/pl/api-cytowan
  - https://cytado.com/citation-api-docs
  - https://cytado.com/pl/api-bibliografii
  - https://cytado.com/pl/api-zrodel-do-tezy
  - https://cytado.com/pl/api-weryfikacji-cytowan
  - https://cytado.com/pl/api-cytowan-dokumentacja
paths:
  /api/ext/chapter-sources:
    post:
      operationId: post_api_ext_chapter_sources
      tags:
      - Api
      summary: POST /api/ext/chapter-sources
      x-source: https://cytado.com/bibliography-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiExtChapterSourcesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST https://cytado.com/api/ext/chapter-sources  -H \"Authorization: Bearer $CYTADO_KEY\"  -H \"Content-Type: application/json\"\
          \  -d '{\n \"topic\": \"screen time in preschool children\",\n \"chapter\": \"Introduction\",\n \"exclude\": []\n}' Full reference,\
          \ every field and error code → What formatting will not fix We format what you send. If the metadata is wrong, the entry will be wrong\
          \ in perfect APA "
  /api/ext/check-bibliography:
    post:
      operationId: post_api_ext_check_bibliography
      tags:
      - Api
      summary: Check whether a citation is real, before a reviewer does
      x-source: https://cytado.com/citation-verification-api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/ext/corpus:
    get:
      operationId: get_api_ext_corpus
      tags:
      - Api
      summary: Enqueue corpus build or read.
      x-source: https://cytado.com/citation-api-docs
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiExtCorpusResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_ext_corpus
      tags:
      - Api
      summary: POST /api/ext/corpus
      x-source: https://cytado.com/citation-api-docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiExtCorpusRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s https://cytado.com/api/ext/corpus  -H "Authorization: Bearer $CYTADO_KEY"  -H "Content-Type: application/json"  -d ''{"topic":"persuasion
          in advertising","langs":["en"],"minCoverage":6,"async":true}'''
  /api/ext/corpus/status:
    get:
      operationId: get_api_ext_corpus_status
      tags:
      - Api
      summary: Poll corpus build status.
      x-source: https://cytado.com/citation-api-docs
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiExtCorpusStatusResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_ext_corpus_status
      tags:
      - Api
      summary: POST /api/ext/corpus/status
      x-source: https://cytado.com/citation-api-docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiExtCorpusStatusRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s https://cytado.com/api/ext/corpus/status  -H "Authorization: Bearer $CYTADO_KEY"  -H "Content-Type: application/json"  -d
          ''{"jobId":82,"topic":"persuasion in advertising","langs":["en"]}'''
  /api/ext/find-source:
    post:
      operationId: post_api_ext_find_source
      tags:
      - Api
      summary: POST /api/ext/find-source
      x-source: https://cytado.com/citation-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiExtFindSourceRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://cytado.com/api/ext/find-source  -H \"Authorization: Bearer $CYTADO_KEY\"  -H \"Content-Type: application/json\"\
          \  -d '{\n \"items\": [{\n \"id\": \"c1\",\n \"claim\": \"Children aged 2-5 spend on average more than two hours a day in front of a\
          \ screen.\",\n \"hint\": \"screen time in preschool children\"\n }],\n \"langs\": [\"en\"]\n }' {\n \"results\": [{\n \"id\": \"c1\"\
          ,\n \"found\": true,\n \"source\": {\n \"title\": \"…"
  /api/ext/usage:
    get:
      operationId: get_api_ext_usage
      tags:
      - Api
      summary: GET /api/ext/usage
      x-source: https://cytado.com/citation-api-docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: python
        snippet: "requests.get(\n \"https://cytado.com/api/ext/usage\",\n headers={\"Authorization\": f\"Bearer {os.environ['CYTADO_KEY']}\"},\n\
          \ timeout=60,\n)"
    post:
      operationId: post_api_ext_usage
      tags:
      - Api
      summary: POST /api/ext/usage
      x-source: https://cytado.com/citation-api-docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiExtUsageRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl Python Node.js curl -s -H \"Authorization: Bearer $CYTADO_KEY\"  https://cytado.com/api/ext/usage import os, requests\n\
          r = requests.get(\n \"https://cytado.com/api/ext/usage\",\n headers={\"Authorization\": f\"Bearer {os.environ['CYTADO_KEY']}\"},\n timeout=60,\n\
          )\nprint(r.json()) const r = await fetch(\"https://cytado.com/api/ext/usage\", {\n headers: { Authorization: `Bearer ${process.env.CYTADO_KEY}`\
          \ },\n})"
  /api/mcp:
    get:
      operationId: get_api_mcp
      tags:
      - Api
      summary: GET /api/mcp
      x-source: https://cytado.com/citation-api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: http https://cytado.com/api/mcp \
  /chapter-sources:
    post:
      operationId: post_chapter_sources
      tags:
      - Chapter Sources
      summary: Citation API with real page numbers
      x-source: https://cytado.com/citation-api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /cytado-hook:
    post:
      operationId: post_cytado_hook
      tags:
      - Cytado Hook
      summary: HTTP notifications (webhooks).
      x-source: https://cytado.com/citation-api-docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCytadoHookRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /find-source:
    post:
      operationId: post_find_source
      tags:
      - Find Source
      summary: Citation API with real page numbers
      x-source: https://cytado.com/citation-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFindSourceRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFindSourceResponse'
      x-evidence:
        kind: documentation
  /usage:
    get:
      operationId: get_usage
      tags:
      - Usage
      summary: Citation API with real page numbers
      x-source: https://cytado.com/citation-api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApiExtChapterSourcesRequest:
      type: object
      properties:
        topic:
          type: string
        chapter:
          type: string
        exclude:
          type: array
          items: {}
    GetApiExtCorpusResponse:
      type: object
      properties:
        jobId:
          type: integer
          description: Job identifier for async builds.
        coverage:
          type: integer
          description: Current coverage level.
        coverageWprost:
          type: integer
          description: On‑topic coverage.
        corpusReady:
          type: boolean
          description: Whether corpus is ready.
        async:
          type: boolean
          description: Echo of async flag.
    PostApiExtCorpusRequest:
      type: object
      properties:
        topic:
          type: string
        langs:
          type: array
          items:
            type: string
        minCoverage:
          type: integer
        async:
          type: boolean
    GetApiExtCorpusStatusResponse:
      type: object
      properties:
        jobId:
          type: integer
          description: Job identifier.
        status:
          type: string
          description: One of queued, running, done, failed, unknown.
        ready:
          type: boolean
          description: True when corpus is ready.
        coverage:
          type: integer
          description: Current coverage.
        coverageWprost:
          type: integer
          description: On‑topic coverage.
    PostApiExtCorpusStatusRequest:
      type: object
      properties:
        jobId:
          type: integer
        topic:
          type: string
        langs:
          type: array
          items:
            type: string
    PostApiExtFindSourceRequest:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              claim:
                type: string
              hint:
                type: string
        langs:
          type: array
          items:
            type: string
    PostApiExtUsageRequest:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              claim:
                type: string
              hint:
                type: string
        langs:
          type: array
          items:
            type: string
        harvestOnMiss:
          type: boolean
    PostCytadoHookRequest:
      type: object
      properties:
        event:
          type: string
          description: Event type (e.g., job.completed).
        at:
          type: integer
          description: Timestamp of the event.
        data:
          type: object
          description: Event payload containing jobId, topic, coverage, coverageWprost.
      required:
      - event
      - at
      - data
    PostFindSourceRequest:
      type: object
      properties:
        items:
          type: array
          description: Array of citation requests
        items.id:
          type: string
          description: Identifier for the request
        items.claim:
          type: string
          description: The sentence or claim to be sourced
        items.hint:
          type: string
          description: Optional hint to improve search
        langs:
          type: array
          description: Preferred languages (e.g., ["en"])
      required:
      - items
      - items.id
      - items.claim
    PostFindSourceResponse:
      type: object
      properties:
        results:
          type: array
          description: Array of resolved citations
        results.id:
          type: string
          description: Matches the request id
        results.found:
          type: boolean
          description: Whether a supporting source was found
        results.source.title:
          type: string
          description: Title of the source
        results.source.authors:
          type: string
          description: Authors of the source
        results.source.year:
          type: integer
          description: Publication year
        results.source.page_from:
          type: integer
          description: Printed page number where the claim appears
        results.source.page_from_label:
          type: string
          description: Label of the page number
        results.source.snippet:
          type: string
          description: Excerpt containing the claim
        results.source.relevance:
          type: integer
          description: Relevance score
        rozliczenie:
          type: object
          description: Billing information
        rozliczenie.cytowania:
          type: integer
          description: Number of citations billed
        rozliczenie.tematy:
          type: integer
          description: Number of topics billed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Chapter Sources
- name: Cytado Hook
- name: Find Source
- name: Usage