WritersLogic Verifiable AI Agent Hub Verify References API

openapi: 3.2.0
info:
  title: WritersLogic Verifiable AI Agent Hub Verify References API
  version: 2.0.0
  description: Pay-per-call agents settled in USDC on Base via x402. Every response carries a signed provenance envelope.
  contact:
    name: WritersLogic
    url: https://writerslogic.com/agents
    email: agents@writerslogic.com
servers:
- url: https://agents.writerslogic.com
tags:
- name: Verify References
paths:
  /api/v1/verify-references:
    post:
      operationId: reference_verifier
      summary: Bibliography Reference Verifier
      description: 'Checks every reference in a bibliography against Crossref, OpenAlex, arXiv and Europe PMC and leads with a verdict (FIX_REQUIRED, REVIEW_RECOMMENDED, INCOMPLETE or ALL_VERIFIED), a confidence, a one-line headline, the next step and a prioritized fix list. Input: BibTeX, LaTeX \bibitem, a plain-text list (APA, IEEE, Vancouver), an arXiv id (read via ar5iv), a PDF URL, or just a list of DOIs, arXiv ids and PMIDs. Each reference is VERIFIED, METADATA_MISMATCH (field-level year, author, title, venue and DOI diffs), DOI_RESOLVES_TO_DIFFERENT_WORK, NOT_FOUND (likely fabricated or mistyped), RETRACTED or HAS_CORRECTION (Crossref updated-by, OpenAlex is_retracted, Europe PMC notices), PREPRINT_NOW_PUBLISHED (with the version of record), DUPLICATE_ENTRY or UNRESOLVABLE (an index was down; reported as a partial result, never as NOT_FOUND). With manuscript text, unresolved \cite keys and uncited entries are reported. All verdicts are computed in code with zero model calls; checkSupport adds one fast-tier call judging whether each cited abstract supports its citing sentence, both quotes verified. Limited to indexed works: books, theses, standards and web pages are often NOT_FOUND or UNRESOLVABLE, and a clean result is not an endorsement of the cited claim.


        Price: 0.50 USDC on Base (x402).'
      x-x402-price-usdc: '0.50'
      x-x402-amount: '500000'
      x-payment-info:
        protocols:
        - x402
        price:
          mode: fixed
          currency: USD
          amount: '0.50'
      x-audience: research
      x-sample-url: https://agents.writerslogic.com/api/v1/samples/reference-verifier
      security:
      - x402: []
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                bibtex:
                  type: string
                  minLength: 10
                  maxLength: 400000
                  description: BibTeX/BibLaTeX text (the contents of a .bib file).
                latex:
                  type: string
                  minLength: 10
                  maxLength: 400000
                  description: LaTeX source with a thebibliography environment (\bibitem) or embedded filecontents .bib; \cite commands supply citation contexts and are checked against the entries.
                references:
                  type: string
                  minLength: 10
                  maxLength: 200000
                  description: Plain-text reference list (numbered, blank-line separated, or one per line; APA, IEEE, Vancouver, Chicago).
                arxivId:
                  type: string
                  minLength: 4
                  maxLength: 80
                  description: arXiv id or URL; references are read from the ar5iv HTML (.ltx_bibitem), falling back to the PDF.
                pdfUrl:
                  type: string
                  minLength: 8
                  maxLength: 2000
                  description: Public PDF URL. Text extraction is best-effort (Word and Google Docs exports work best).
                identifiers:
                  type: array
                  minItems: 1
                  maxItems: 150
                  items:
                    type: string
                    minLength: 3
                    maxLength: 300
                  description: 'Bare identifiers instead of a bibliography: up to 150 DOIs (bare, doi: or doi.org URL), arXiv ids or URLs, or PMIDs (bare, PMID: or PubMed URL), mixed freely. Each is resolved and checked for retraction, correction and a published version of record.'
                manuscript:
                  type: string
                  minLength: 10
                  maxLength: 400000
                  description: 'Optional manuscript text (LaTeX or plain) that supplies citation contexts: \cite keys, [n] numbers or Author (year) citations.'
                checkSupport:
                  type: boolean
                  description: Needs manuscript text (or latex, arxivId, pdfUrl). Spends one fast-tier model call to judge whether each cited abstract supports its citing sentence (at most 20 citations).
            example:
              references: '[1] Wakefield AJ, Murch SH, Anthony A, et al. Ileal-lymphoid-nodular hyperplasia, non-specific colitis, and pervasive developmental disorder in children. Lancet. 1998;351(9103):637-41.

                [2] Abbott BP, et al. Observation of gravitational waves from a binary black hole merger. arXiv:1602.03837'
      responses:
        '200':
          description: Paid result with provenance
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verdict:
                        type: string
                        enum:
                        - FIX_REQUIRED
                        - REVIEW_RECOMMENDED
                        - INCOMPLETE
                        - ALL_VERIFIED
                        description: 'FIX_REQUIRED: a retracted, unfindable or wrongly-identified reference or an unresolved \cite key. REVIEW_RECOMMENDED: corrections, metadata mismatches, preprints with a published version, duplicates. INCOMPLETE: nothing wrong in what could be checked, but some references could not be. ALL_VERIFIED: every reference resolved and clean.'
                      confidence:
                        type: integer
                        description: '0-100: share of the bibliography whose lookup completed. Low means re-run, not that the references are bad.'
                      headline:
                        type: string
                        description: One-sentence human summary.
                      nextStep:
                        type: string
                        description: The concrete next action.
                      priorityActions:
                        type: array
                        items:
                          type: object
                          description: index, key, status, severity (critical|review), action; critical first, at most 10.
                      moreActions:
                        type: integer
                        description: Flagged references beyond the priorityActions cap.
                      partial:
                        type: boolean
                        description: True when some references were not checked; coverage.failedSources names the cause.
                      input:
                        type: object
                        description: kind, referencesParsed, referencesChecked (capped at 150), parse notes.
                      summary:
                        type: object
                        description: total, flagged (not VERIFIED), byStatus counts.
                      references:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                            key:
                              type: string
                            reference:
                              type: object
                              description: 'Parsed fields: title, authors, year, venue, doi, arxivId, pmid.'
                            status:
                              type: string
                              enum:
                              - VERIFIED
                              - METADATA_MISMATCH
                              - DOI_RESOLVES_TO_DIFFERENT_WORK
                              - NOT_FOUND
                              - RETRACTED
                              - HAS_CORRECTION
                              - PREPRINT_NOW_PUBLISHED
                              - DUPLICATE_ENTRY
                              - UNRESOLVABLE
                            issues:
                              type: array
                              items:
                                type: object
                                description: status + detail; every problem found, the first by precedence is the status.
                            diffs:
                              type: array
                              items:
                                type: object
                                description: field (year|authors|title|venue|doi), reference, found.
                            match:
                              type: object
                              description: Matched record with score, titleSimilarity, authorOverlap, yearScore.
                            integrity:
                              type: object
                              description: Retraction/correction status and notices (Crossref updated-by, OpenAlex is_retracted, Europe PMC), merged across near-identical records.
                            publishedVersion:
                              type: object
                              description: 'For a preprint: the version of record (doi, venue, year).'
                            citations:
                              type: object
                              description: count and up to 3 citing sentences.
                            support:
                              type: array
                              items:
                                type: object
                                description: verdict SUPPORTS|PARTIAL|DOES_NOT_SUPPORT|CANNOT_ASSESS with verified claimQuote and sourceQuote.
                      citationCheck:
                        type: object
                        description: mode (latex|numeric|ar5iv|author-year|none), unresolvedKeys, uncitedEntries.
                      support:
                        type: object
                        description: Whether the model support check ran, how many citations were sent, how many skipped over the cap.
                      llmCalls:
                        type: integer
                        description: 0 on the deterministic path; 1 when checkSupport is set and at least one citation has an abstract.
                      decidedBy:
                        type: string
                        enum:
                        - code
                        - code+model
                      thresholds:
                        type: object
                        description: Matching thresholds applied.
                      coverage:
                        type: object
                        description: Upstream calls used, skipped references, failed sources.
                  _provenance:
                    type: object
                    description: C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance
                required:
                - data
                - _provenance
        '400':
          description: Invalid request (no payment consumed)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '401':
          description: Invalid X-API-KEY
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '402':
          description: Payment required or invalid
          content:
            application/json:
              schema:
                type: object
                description: x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)
                properties:
                  x402Version:
                    type: integer
                  error:
                    type: string
                  code:
                    type: string
                  resource:
                    type: object
                  accepts:
                    type: array
                    items:
                      type: object
                  extensions:
                    type: object
        '502':
          description: Upstream failure; the payment is released or not settled
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
      tags:
      - Verify References
components:
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment payload (base64) sent after a 402 challenge
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY