openapi: 3.1.0
info:
  title: Nadeshiko API
  description: |
    Thank you for using the Nadeshiko API! This API lets you search Japanese dialogue segments across anime and J-Drama, with translations and contextual metadata.

    ### Authentication
    All public API requests require an API key passed in the `Authorization` header as `Bearer <api_key>`.
    You can register and generate your key on the [developer page](https://nadeshiko.co/user/developer), where you can also check your current usage.

    ### Request Headers
    The only required application-level request header for the public API is:

    - `Authorization: Bearer <api_key>`

    Public API endpoints do not currently expose custom request ID or rate limit response headers.

    ### Rate Limit
    Each API key is limited to **150 requests per minute**. Exceeding this limit will return a `429 Too Many Requests` response.
    The `429` response body distinguishes between short-term rate limiting and monthly quota exhaustion.

    ### Quota
    Each account has a monthly quota of **5,000 requests**. Once exceeded, further requests will be rejected until the next month.
    To request a quota increase, reach out via the [contact page](https://nadeshiko.co/about).

  version: 2.2.2
  contact:
    name: Nadeshiko Team
    url: https://nadeshiko.co
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  x-logo:
    url: ./logo.png
    altText: Nadeshiko
    href: https://nadeshiko.co

servers:
  - description: Production server
    url: https://api.nadeshiko.co

tags:
  - name: Search
    description: |
      Search endpoints for querying Japanese segments across indexed media.

  - name: Media
    description: |
      Media endpoints for browsing anime and J-Drama entries, episodes, and segments.

  - name: Collections
    description: |
      Collection endpoints for managing saved segment collections.

  - name: User
    description: |
      User endpoints for profile data, excluded media, and activity history.

  - name: Activity
    description: |
      Activity endpoints for tracking and querying the authenticated user's activity history.

  - name: Stats
    description: |
      Statistics endpoints for corpus coverage and word frequency data.

  - name: Admin
    x-internal: true
    description: |
      Administrative endpoints for system management, queue monitoring, and automated review.

x-tagGroups:
  - name: Core
    tags:
      - Search
      - Media
  - name: User
    tags:
      - User
      - Activity
      - Collections
  - name: Misc
    tags:
      - Stats

paths:
  # Search endpoints
  "/v1/search":
    $ref: "./paths/search/v1_search.yaml"
  "/v1/search/stats":
    $ref: "./paths/search/v1_search_stats.yaml"
  "/v1/search/words":
    $ref: "./paths/search/v1_search_words.yaml"
  "/v1/search/media":
    $ref: "./paths/search/v1_search_media.yaml"
  # Stats endpoints
  "/v1/stats/overview":
    $ref: "./paths/stats/v1_stats_overview.yaml"
  "/v1/stats/covered-words":
    $ref: "./paths/stats/v1_stats_covered_words.yaml"
  "/v1/stats/covered-words/update":
    $ref: "./paths/stats/v1_stats_covered_words_update.yaml"
  # Media endpoints
  "/v1/media":
    $ref: "./paths/media/v1_media.yaml"

  # Segment standalone query by segmentPublicId (static prefix before {mediaPublicId})
  "/v1/media/segments/{segmentPublicId}":
    $ref: "./paths/media/v1_media_segments_publicId.yaml"
  "/v1/media/segments/{segmentPublicId}/context":
    $ref: "./paths/media/v1_media_segments_publicId_context.yaml"
  "/v1/media/segments/{segmentPublicId}/revisions":
    $ref: "./paths/media/v1_media_segments_publicId_revisions.yaml"

  # Parameterized media route — MUST come after all static /v1/media/* routes
  "/v1/media/{mediaPublicId}":
    $ref: "./paths/media/v1_media_id.yaml"

  # Episode endpoints (nested under media)
  "/v1/media/{mediaPublicId}/episodes":
    $ref: "./paths/media/v1_media_mediaId_episodes.yaml"
  "/v1/media/{mediaPublicId}/episodes/{episodeNumber}":
    $ref: "./paths/media/v1_media_mediaId_episodes_episodeNumber.yaml"

  # Segment endpoints (nested under episodes)
  "/v1/media/{mediaPublicId}/episodes/{episodeNumber}/segments":
    $ref: "./paths/media/v1_media_mediaId_episodes_episodeNumber_segments.yaml"
  "/v1/media/{mediaPublicId}/episodes/{episodeNumber}/segments/batch":
    $ref: "./paths/media/v1_media_mediaId_episodes_episodeNumber_segments_batch.yaml"

  # User endpoints
  "/v1/user/me":
    $ref: "./paths/user/v1_user_me.yaml"
  "/v1/user/excluded-media":
    $ref: "./paths/user/v1_user_excluded_media.yaml"
  "/v1/user/excluded-media/{mediaPublicId}":
    $ref: "./paths/user/v1_user_excluded_media_mediaPublicId.yaml"
  "/v1/user/reports":
    $ref: "./paths/user/v1_user_reports.yaml"
  "/v1/user/preferences":
    $ref: "./paths/user/v1_user_preferences.yaml"
  "/v1/user/activity":
    $ref: "./paths/user/v1_user_activity.yaml"
  "/v1/user/activity/heatmap":
    $ref: "./paths/user/v1_user_activity_heatmap.yaml"
  "/v1/user/activity/stats":
    $ref: "./paths/user/v1_user_activity_stats.yaml"
  "/v1/user/activity/date/{date}":
    $ref: "./paths/user/v1_user_activity_date_date.yaml"
  "/v1/user/activity/{activityId}":
    $ref: "./paths/user/v1_user_activity_id.yaml"
  "/v1/user/export":
    $ref: "./paths/user/v1_user_export.yaml"
  "/v1/user/labs":
    $ref: "./paths/user/v1_user_labs.yaml"
  "/v1/user/labs/{key}":
    $ref: "./paths/user/v1_user_labs_key.yaml"

  # Collection endpoints
  "/v1/collections":
    $ref: "./paths/collections/v1_collections.yaml"
  "/v1/collections/{collectionPublicId}":
    $ref: "./paths/collections/v1_collections_id.yaml"
  "/v1/collections/{collectionPublicId}/segments":
    $ref: "./paths/collections/v1_collections_id_segments.yaml"
  "/v1/collections/{collectionPublicId}/search":
    $ref: "./paths/collections/v1_collections_id_search.yaml"
  "/v1/collections/{collectionPublicId}/segments/{segmentPublicId}":
    $ref: "./paths/collections/v1_collections_id_segments_segmentId.yaml"
  "/v1/collections/{collectionPublicId}/stats":
    $ref: "./paths/collections/v1_collections_id_stats.yaml"

  # Admin endpoints
  "/v1/admin/reports":
    $ref: "./paths/admin/v1_admin_reports.yaml"
  "/v1/admin/reports/batch":
    $ref: "./paths/admin/v1_admin_reports_batch.yaml"
  "/v1/admin/reports/bulk":
    $ref: "./paths/admin/v1_admin_reports_bulk.yaml"
  "/v1/admin/reports/{reportId}":
    $ref: "./paths/admin/v1_admin_reports_id.yaml"
  "/v1/admin/media/audits":
    $ref: "./paths/admin/v1_admin_media_audits.yaml"
  "/v1/admin/media/audits/{name}":
    $ref: "./paths/admin/v1_admin_media_audits_name.yaml"
  "/v1/admin/media/audits/{name}/run":
    $ref: "./paths/admin/v1_admin_media_audits_name_run.yaml"
  "/v1/admin/media/audits/runs":
    $ref: "./paths/admin/v1_admin_media_audits_runs.yaml"
  "/v1/admin/media/audits/runs/{auditRunId}":
    $ref: "./paths/admin/v1_admin_media_audits_runs_id.yaml"
  "/v1/admin/announcement":
    $ref: "./paths/admin/v1_admin_announcement.yaml"

components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: "Send `Authorization: Bearer <api_key>`. Get your API key from https://nadeshiko.co/user/developer"

    SessionCookie:
      type: apiKey
      in: cookie
      name: nadeshiko.session_token
      description: Session authentication via cookie