openapi: 3.0.0
info:
  title: 'Events API — Islamic Network'
  description: 'What happened / what is observed on the days of the Islamic calendar — consumed by pray.islamic.network (day pages), aladhan.com (holy-day features) and third parties. Every response is wrapped in the `{code, status, data}` envelope shared across Islamic Network APIs; list endpoints add a `meta` sibling. Language keys are BCP 47 tags (`ar`, `en`, `ur`, …, and `ar-Latn` for transliteration); empty values are omitted entirely. Lists summarize, item endpoints expand.'
  contact:
    url: 'https://islamic.network'
    email: hello@islamic.network
  version: 1.0.0
servers:
  -
    url: 'https://events.api.islamic.network/v1'
    description: Production
paths:
  '/calendar/{month}':
    get:
      tags:
        - calendar
      summary: 'Events observed in a Hijri month'
      operationId: getMonth
      parameters:
        -
          $ref: '#/components/parameters/month'
      responses:
        '200':
          description: 'The month and its events, each with its date.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { data: { $ref: '#/components/schemas/CalendarMonth' } }, type: object }
        '404':
          $ref: '#/components/responses/Error'
  '/calendar/{month}/{day}':
    get:
      tags:
        - calendar
      summary: 'Events observed on a Hijri day'
      description: "The integration endpoint pray and AlAdhan call. links.day points at the pray API's record for this day when it has one."
      operationId: getDay
      parameters:
        -
          $ref: '#/components/parameters/month'
        -
          $ref: '#/components/parameters/day'
      responses:
        '200':
          description: "The day's events (possibly none)."
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { data: { $ref: '#/components/schemas/CalendarDay' } }, type: object }
        '404':
          $ref: '#/components/responses/Error'
  /calendar/today:
    get:
      tags:
        - calendar
      summary: "Resolve a Gregorian date to its Hijri day's events"
      description: 'Gregorian date → Hijri date (AlAdhan, HJCoSA calendar method) → the events observed that day. Defaults to the server date (UTC).'
      operationId: getToday
      parameters:
        -
          name: date
          in: query
          description: 'Gregorian date as DD-MM-YYYY; defaults to today.'
          schema:
            type: string
            pattern: '^\d{2}-\d{2}-\d{4}$'
            example: 25-06-2026
      responses:
        '200':
          description: 'The resolved date, its month, its events and the next upcoming event.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { data: { $ref: '#/components/schemas/Today' } }, type: object }
        '400':
          $ref: '#/components/responses/Error'
  '/documentation/openapi/{format}':
    get:
      tags:
        - documentation
      summary: 'This specification, as OpenAPI 3'
      operationId: getOpenApiSpec
      parameters:
        -
          name: format
          in: path
          required: true
          schema:
            type: string
            enum:
              - yaml
              - json
      responses:
        '200':
          description: 'The OpenAPI document.'
  /events:
    get:
      tags:
        - events
      summary: 'All events (summaries) in calendar order'
      description: 'Events without `year` are timeless anniversaries; full records live at /events/{slug}.'
      operationId: listEvents
      parameters:
        -
          $ref: '#/components/parameters/page'
        -
          $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'Paginated event summaries.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { meta: { $ref: '#/components/schemas/Meta' }, data: { type: array, items: { $ref: '#/components/schemas/EventSummary' } } }, type: object }
  '/events/{slug}':
    get:
      tags:
        - events
      summary: 'Full event'
      description: 'Title, observed date, historical year, description, the people involved (shared registry slugs) and cross-links into sibling APIs.'
      operationId: getEvent
      parameters:
        -
          $ref: '#/components/parameters/slug'
      responses:
        '200':
          description: 'The event, expanded.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { data: { $ref: '#/components/schemas/EventDetail' } }, type: object }
        '404':
          $ref: '#/components/responses/Error'
  /people:
    get:
      tags:
        - people
      summary: 'People referenced by events'
      description: 'Person slugs are the ecosystem-wide identifiers owned by the People API; `registry` points at the canonical record there.'
      operationId: listPeople
      parameters:
        -
          $ref: '#/components/parameters/page'
        -
          $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'Paginated referenced-person summaries, slug order.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { meta: { $ref: '#/components/schemas/Meta' }, data: { type: array, items: { $ref: '#/components/schemas/PersonSummary' } } }, type: object }
  '/people/{slug}/events':
    get:
      tags:
        - people
      summary: 'Events involving a person'
      operationId: getPersonEvents
      parameters:
        -
          $ref: '#/components/parameters/slug'
        -
          $ref: '#/components/parameters/page'
        -
          $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'The person and their events, calendar order.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { meta: { $ref: '#/components/schemas/Meta' }, data: { properties: { person: { $ref: '#/components/schemas/PersonHeader' }, events: { type: array, items: { $ref: '#/components/schemas/EventSummary' } } }, type: object } }, type: object }
        '404':
          $ref: '#/components/responses/Error'
  /search:
    get:
      tags:
        - search
      summary: 'Diacritic-folded search across events'
      description: 'Matching is diacritic-folded (Ṣ→s, ā→a, ʿ/ʾ dropped, Arabic tashkīl stripped) across every language key of titles, descriptions and sources — `karbala`, `Karbalāʾ` and `كَرْبَلَاء` all match. Multiple query words AND together.'
      operationId: search
      parameters:
        -
          name: q
          in: query
          description: 'The query; at least 2 characters.'
          required: true
          schema:
            type: string
            example: karbala
            minLength: 2
        -
          $ref: '#/components/parameters/page'
        -
          $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: 'Matching events as summaries with the field paths that matched.'
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - { properties: { meta: { $ref: '#/components/schemas/Meta' }, data: { properties: { query: { type: string }, total: { type: integer }, results: { type: array, items: { $ref: '#/components/schemas/SearchResult' } } }, type: object } }, type: object }
        '400':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Name:
      description: 'Language-keyed text. Keys are BCP 47 tags; `ar-Latn` is the transliteration. Only non-empty languages appear.'
      type: object
      example:
        ar: 'مَوْلِدُ النَّبِيِّ ﷺ'
        ar-Latn: 'Mawlid al-Nabī ﷺ'
        en: 'The birth of the Prophet Muhammad ﷺ'
      additionalProperties:
        type: string
    Prose:
      description: 'Language-keyed prose. `raw` is the authored Markdown; `html` is rendered from it (Arabic-script runs wrapped in `<span lang="ar">`).'
      type: object
      additionalProperties:
        required:
          - raw
          - html
        properties:
          raw:
            description: "OpenAPI document root and shared components. Endpoint annotations live on\nthe v1 controllers; the assembled spec is served by\nGET /v1/documentation/openapi/{yaml|json}."
            type: string
          html:
            type: string
        type: object
    EventDate:
      description: 'The Hijri anniversary an event is observed on — the calendar key. Day-of-month anniversaries, not specific dates.'
      required:
        - month
        - day
      properties:
        month:
          type: integer
          maximum: 12
          minimum: 1
        day:
          type: integer
          maximum: 30
          minimum: 1
      type: object
    Year:
      description: 'When the event actually happened. Present only for historical events; either calendar may be absent (pre-Hijra events have only `gregorian`).'
      properties:
        hijri:
          type: integer
          example: 61
        gregorian:
          type: integer
          example: 680
      type: object
    MonthRef:
      description: 'A Hijri month reference on calendar responses.'
      required:
        - number
        - name
      properties:
        number:
          type: integer
          maximum: 12
          minimum: 1
        name:
          $ref: '#/components/schemas/Name'
      type: object
    PersonRef:
      description: 'A person involved in an event. The slug is the ecosystem-wide identifier owned by the People API; `url` points into that registry.'
      required:
        - slug
        - name
        - url
      properties:
        slug:
          type: string
          example: husayn-ibn-ali
        name:
          $ref: '#/components/schemas/Name'
        url:
          type: string
      type: object
    Links:
      description: 'Cross-links into sibling APIs, present only when there is somewhere to point.'
      properties:
        day:
          description: "The pray API's day record for the observed date."
          type: string
          example: 'https://pray.api.islamic.network/v1/calendar/1/10'
      type: object
    Meta:
      description: 'Pagination block, sibling of `data` on list endpoints.'
      required:
        - total
        - page
        - limit
        - pages
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        pages:
          type: integer
      type: object
    Envelope:
      required:
        - code
        - status
      properties:
        code:
          type: integer
          example: 200
        status:
          type: string
          example: OK
      type: object
    EventSummary:
      required:
        - slug
        - title
        - date
        - url
      properties:
        slug:
          type: string
          example: martyrdom-of-husayn
        title:
          $ref: '#/components/schemas/Name'
        date:
          $ref: '#/components/schemas/EventDate'
        year:
          $ref: '#/components/schemas/Year'
        url:
          type: string
      type: object
    EventDetail:
      required:
        - id
        - slug
        - url
        - title
        - date
      properties:
        id:
          type: string
        slug:
          type: string
        url:
          type: string
        title:
          $ref: '#/components/schemas/Name'
        date:
          $ref: '#/components/schemas/EventDate'
        year:
          $ref: '#/components/schemas/Year'
        description:
          $ref: '#/components/schemas/Prose'
        people:
          type: array
          items:
            $ref: '#/components/schemas/PersonRef'
        source:
          type: string
          example: 'Fazilet Calendar'
        links:
          $ref: '#/components/schemas/Links'
      type: object
    CalendarEvent:
      description: 'An event as listed on the calendar endpoints: year/people when present. The day view omits `date` (it is the path); the month view carries it.'
      required:
        - slug
        - title
        - url
      properties:
        slug:
          type: string
        title:
          $ref: '#/components/schemas/Name'
        date:
          $ref: '#/components/schemas/EventDate'
        year:
          $ref: '#/components/schemas/Year'
        people:
          type: array
          items:
            $ref: '#/components/schemas/PersonRef'
        url:
          type: string
      type: object
    CalendarMonth:
      required:
        - month
        - events
      properties:
        month:
          $ref: '#/components/schemas/MonthRef'
        events:
          type: array
          items:
            $ref: '#/components/schemas/CalendarEvent'
      type: object
    CalendarDay:
      required:
        - date
        - month
        - events
      properties:
        date:
          $ref: '#/components/schemas/EventDate'
        month:
          $ref: '#/components/schemas/MonthRef'
        events:
          type: array
          items:
            $ref: '#/components/schemas/CalendarEvent'
        links:
          $ref: '#/components/schemas/Links'
      type: object
    Today:
      required:
        - date
        - month
        - events
        - next
      properties:
        date:
          properties:
            gregorian:
              type: string
              format: date
              example: '2026-06-25'
            hijri:
              properties:
                year:
                  type: integer
                  example: 1448
                month:
                  type: integer
                  example: 1
                day:
                  type: integer
                  example: 10
              type: object
          type: object
        month:
          oneOf:
            -
              $ref: '#/components/schemas/MonthRef'
          nullable: true
        events:
          type: array
          items:
            $ref: '#/components/schemas/CalendarEvent'
        links:
          $ref: '#/components/schemas/Links'
        next:
          oneOf:
            -
              $ref: '#/components/schemas/EventSummary'
          nullable: true
          description: 'The next upcoming event, wrapping across the year.'
      type: object
    PersonSummary:
      required:
        - slug
        - name
        - events
        - url
        - registry
      properties:
        slug:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        events:
          description: 'How many events involve this person.'
          type: integer
        url:
          description: "This API's event list for the person."
          type: string
        registry:
          description: 'The canonical person record on the People API.'
          type: string
      type: object
    PersonHeader:
      required:
        - slug
        - name
        - registry
      properties:
        slug:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        registry:
          type: string
      type: object
    SearchResult:
      required:
        - type
        - matched_in
        - id
        - slug
        - title
        - date
        - url
      properties:
        type:
          type: string
          enum:
            - event
        matched_in:
          description: 'Language-keyed field paths that matched, e.g. `title.ar-Latn`.'
          type: array
          items:
            type: string
        id:
          type: string
        slug:
          type: string
        title:
          $ref: '#/components/schemas/Name'
        date:
          $ref: '#/components/schemas/EventDate'
        year:
          $ref: '#/components/schemas/Year'
        url:
          type: string
      type: object
  responses:
    Error:
      description: 'Error — the envelope with a message string as `data`.'
      content:
        application/json:
          schema:
            required:
              - code
              - status
              - data
            properties:
              code:
                type: integer
                example: 404
              status:
                type: string
                example: 'NOT FOUND'
              data:
                type: string
                example: 'Event not found.'
            type: object
  parameters:
    page:
      name: page
      in: query
      description: 'Page number (default 1).'
      schema:
        type: integer
        default: 1
        minimum: 1
    limit:
      name: limit
      in: query
      description: 'Records per page (default 50, max 200).'
      schema:
        type: integer
        default: 50
        maximum: 200
        minimum: 1
    month:
      name: month
      in: path
      description: 'Hijri month number.'
      required: true
      schema:
        type: integer
        maximum: 12
        minimum: 1
    day:
      name: day
      in: path
      description: 'Hijri day of month.'
      required: true
      schema:
        type: integer
        maximum: 30
        minimum: 1
    slug:
      name: slug
      in: path
      description: "The record's canonical URL key."
      required: true
      schema:
        type: string
tags:
  -
    name: events
    description: 'The events themselves'
  -
    name: calendar
    description: 'Events by Hijri date'
  -
    name: people
    description: 'People referenced by events (shared registry slugs)'
  -
    name: search
    description: 'Diacritic-folded search'
  -
    name: documentation
    description: 'This specification'