openapi: 3.0.3
info:
  title: US Army Public Articles API
  description: The US Army Public API provides public access to Army news articles, events, personnel information, and other publicly available Army information. The API is documented with Swagger UI at api.army.mil.
  version: 2.0.0
  contact:
    name: US Army Web Support Team
    url: https://api.army.mil/
  license:
    name: Public Domain
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://api.army.mil/api/v1
  description: US Army Public API production server
tags:
- name: Articles
paths:
  /article/{id}:
    get:
      operationId: getArticleById
      summary: Get Article By ID
      description: Find and retrieve a specific Army news article by its unique identifier.
      tags:
      - Articles
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the article
        schema:
          type: string
      responses:
        '200':
          description: Successful response with article data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: Article not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /articles:
    get:
      operationId: getArticles
      summary: Get Articles
      description: Retrieve a list of publicly available US Army news articles, filtered by various criteria.
      tags:
      - Articles
      parameters:
      - name: q
        in: query
        required: false
        description: Search query string to filter articles by content
        schema:
          type: string
      - name: tag
        in: query
        required: false
        description: Filter by article tag
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of articles to return
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        required: false
        description: Number of articles to skip for pagination
        schema:
          type: integer
          default: 0
      - name: from
        in: query
        required: false
        description: Start date filter in ISO 8601 format
        schema:
          type: string
          format: date
      - name: to
        in: query
        required: false
        description: End date filter in ISO 8601 format
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleList'
components:
  schemas:
    ArticleList:
      type: object
      properties:
        total:
          type: integer
          description: Total number of articles matching the query
        limit:
          type: integer
          description: Number of articles per page
        offset:
          type: integer
          description: Pagination offset
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
    Article:
      type: object
      description: A US Army news article or content item
      properties:
        id:
          type: string
          description: Unique article identifier
        title:
          type: string
          description: Article headline or title
        summary:
          type: string
          description: Brief summary or lead paragraph
        body:
          type: string
          description: Full article body text
        author:
          type: string
          description: Article author or byline
        publishedDate:
          type: string
          format: date-time
          description: Publication date and time
        updatedDate:
          type: string
          format: date-time
          description: Last update date and time
        tags:
          type: array
          items:
            type: string
          description: Subject tags for the article
        imageUrl:
          type: string
          format: uri
          description: URL to the article's featured image
        url:
          type: string
          format: uri
          description: Canonical URL for the article
        sourceOrg:
          type: string
          description: Source Army organization or command
      required:
      - id
      - title
      - publishedDate
    Error:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error description