openapi: 3.2.0
info:
  title: Urantia Papers Citation API
  version: 1.0.0
  contact:
    name: urantia.dev
    url: https://docs.urantia.dev/help
    email: kelson@urantia.dev
  license:
    name: MIT
    url: https://github.com/urantia-hub/urantia-dev-api/blob/main/LICENSE
  termsOfService: https://docs.urantia.dev/terms-of-service
  description: 'Operations tagged Citation across 2 of this provider''s published API definitions: urantia-papers-openapi.json, urantia-papers-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.urantia.dev
  description: Production
- url: http://localhost:3000
  description: Local development
security: []
tags:
- name: Citation
paths:
  /cite:
    get:
      operationId: getCitation
      tags:
      - Citation
      summary: Format a citation for a passage
      description: 'Generate a formatted citation for any passage of the Urantia Papers. Supports APA, MLA, Chicago, and BibTeX styles.


        Reference formats accepted:

        - **standardReferenceId**: "196:2.1" (paperId:sectionId.paragraphId)

        - **globalId**: "1:196.2.1" (partId:paperId.sectionId.paragraphId)

        - **paperSectionParagraphId**: "196.2.1" (paperId.sectionId.paragraphId)'
      parameters:
      - schema:
          type: string
          minLength: 1
        required: true
        name: ref
        in: query
        example: '2:5.1'
      - schema:
          type: string
          enum:
          - apa
          - mla
          - chicago
          - bibtex
          default: apa
        required: false
        name: style
        in: query
      responses:
        '200':
          description: Formatted citation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ref:
                        type: string
                      style:
                        type: string
                        enum:
                        - apa
                        - mla
                        - chicago
                        - bibtex
                      citation:
                        type: string
                    required:
                    - ref
                    - style
                    - citation
                required:
                - data
              example:
                data:
                  ref: '2:5.1'
                  style: apa
                  citation: The Urantia Book. (1955). Urantia Foundation. Paper 2, Section 5, Paragraph 1.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Invalid reference format
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Too many requests
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    servers:
    - url: https://api.urantia.dev
      description: Production
    - url: http://localhost:3000
      description: Local development
components:
  headers:
    X-RateLimit-Reset:
      description: The time the window resets, in Unix seconds.
      schema:
        type: integer
      example: 1791152213
    X-RateLimit-Remaining:
      description: The number of requests left in the current window.
      schema:
        type: integer
      example: 199
    X-RateLimit-Limit:
      description: The number of requests allowed in the current window.
      schema:
        type: integer
      example: 200
  schemas:
    ProblemDetails:
      type: object
      description: An RFC 9457 problem details object. Every error response uses it.
      properties:
        type:
          type: string
          format: uri
          description: A URI that names the error type.
        title:
          type: string
          description: The short name of the status.
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: What went wrong in this request.
      required:
      - type
      - title
      - status
      - detail
      example:
        type: https://urantia.dev/errors/not-found
        title: Not Found
        status: 404
        detail: Paragraph not found
x-refined-from:
- urantia-papers-openapi.json
- urantia-papers-openapi.json