api.yaml

openapi: 3.0.3
info:
  title: Alignment Research Feed API
  description: |
    API for accessing AI alignment research articles, managing reading lists,
    and getting personalized recommendations.
  version: 1.0.0
  contact:
    name: Alignment Research Feed
    url: https://alignmentfeed.org

servers:
  - url: https://api.alignmentfeed.org
    description: Production server

security:
  - BearerAuth: []

tags:
  - name: Articles
    description: Article listing, search, and details
  - name: User Interactions
    description: Reading status and ratings (requires authentication)
  - name: Recommendations
    description: Personalized article recommendations
  - name: API Tokens
    description: Manage API tokens (requires Auth0 authentication)
  - name: RSS
    description: Syndication feed for alignment research articles

paths:
  /v1/articles:
    get:
      tags:
        - Articles
      summary: List articles
      description: |
        List and search alignment research articles with filtering, sorting, and pagination.
        Results are paginated and can be filtered by source, date range, and text search.
      operationId: listArticles
      security:
        - {}
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/Sort"
        - $ref: "#/components/parameters/FilterSourcesAllowlist"
        - $ref: "#/components/parameters/FilterSourcesBlocklist"
        - $ref: "#/components/parameters/FilterTitleFulltext"
        - $ref: "#/components/parameters/FilterAuthorsFulltext"
        - $ref: "#/components/parameters/FilterCategory"
        - $ref: "#/components/parameters/FilterPublishedAfter"
        - $ref: "#/components/parameters/FilterPublishedBefore"
      responses:
        "200":
          description: List of articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/{article_id}:
    get:
      tags:
        - Articles
      summary: Get article by ID
      description: Retrieve full details of a specific article by its hash ID.
      operationId: getArticle
      security:
        - {}
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ArticleId"
      responses:
        "200":
          description: Article details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Article"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/{article_id}/similar:
    get:
      tags:
        - Articles
      summary: Get similar articles
      description: |
        Find articles similar to the given article using vector similarity search.
        Always returns up to 10 similar articles.
      operationId: getSimilarArticles
      security:
        - {}
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ArticleId"
      responses:
        "200":
          description: List of similar articles (up to 10)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/semantic-search:
    post:
      tags:
        - Articles
      summary: Semantic search
      description: |
        Search for articles semantically similar to the given text.
      operationId: semanticSearchArticles
      security:
        - {}
        - BearerAuth: []
      requestBody:
        description: Search text and optional parameters
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SemanticSearchRequest"
      responses:
        "200":
          description: List of semantically similar articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: Embedding service unavailable (null driver configured)

  /v1/articles/recommended:
    get:
      tags:
        - Recommendations
      summary: Get personalized recommendations
      description: |
        Get personalized article recommendations based on the user's rating history.
        Always returns up to 100 recommended articles.
      operationId: getRecommendedArticles
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of recommended articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/unreviewed:
    get:
      tags:
        - User Interactions
      summary: List unreviewed articles
      description: List articles the authenticated user has not yet reviewed (rated or marked as read).
      operationId: listUnreviewedArticles
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: List of unreviewed articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/liked:
    get:
      tags:
        - User Interactions
      summary: List liked articles
      description: List articles the authenticated user has given a thumbs up.
      operationId: listLikedArticles
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: List of liked articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/disliked:
    get:
      tags:
        - User Interactions
      summary: List disliked articles
      description: List articles the authenticated user has given a thumbs down.
      operationId: listDislikedArticles
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: List of disliked articles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticlesListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/{article_id}/read/{read}:
    post:
      tags:
        - User Interactions
      summary: Mark article as read/unread
      description: Mark an article as read or unread for the authenticated user.
      operationId: setArticleReadStatus
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ArticleId"
        - name: read
          in: path
          required: true
          description: Whether to mark as read (true) or unread (false)
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "204":
          description: Read status updated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/{article_id}/thumbs_up/{thumbs_up}:
    post:
      tags:
        - User Interactions
      summary: Set thumbs up rating
      description: Set or clear the thumbs up rating for an article.
      operationId: setArticleThumbsUp
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ArticleId"
        - name: thumbs_up
          in: path
          required: true
          description: Whether to set (true) or clear (false) thumbs up
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "204":
          description: Thumbs up rating updated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/articles/{article_id}/thumbs_down/{thumbs_down}:
    post:
      tags:
        - User Interactions
      summary: Set thumbs down rating
      description: Set or clear the thumbs down rating for an article.
      operationId: setArticleThumbsDown
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/ArticleId"
        - name: thumbs_down
          in: path
          required: true
          description: Whether to set (true) or clear (false) thumbs down
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "204":
          description: Thumbs down rating updated successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/tokens:
    get:
      tags:
        - API Tokens
      summary: List API tokens
      description: |
        List all API tokens for the authenticated user.
        Only available with Auth0 authentication (not API tokens).
      operationId: listApiTokens
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of API tokens
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiTokenListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - API Tokens
      summary: Create API token
      description: |
        Create a new API token for the authenticated user.
        Only available with Auth0 authentication (not API tokens).
        Maximum 10 active tokens per user.
      operationId: createApiToken
      security:
        - BearerAuth: []
      requestBody:
        description: Optional token configuration (name)
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiTokenRequest"
      responses:
        "201":
          description: API token created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateApiTokenResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: Maximum token limit reached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/tokens/{token_id}:
    delete:
      tags:
        - API Tokens
      summary: Revoke API token
      description: |
        Revoke an API token by its ID.
        Only available with Auth0 authentication (not API tokens).
      operationId: revokeApiToken
      security:
        - BearerAuth: []
      parameters:
        - name: token_id
          in: path
          required: true
          description: Token UUID to revoke
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Token revoked successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /rss:
    get:
      tags:
        - RSS
      summary: RSS feed
      description: |
        Get an RSS feed of alignment research articles.
        Supports the same filtering parameters as the articles list endpoint.
      operationId: getRssFeed
      security:
        - {}
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/Sort"
        - $ref: "#/components/parameters/FilterSourcesAllowlist"
        - $ref: "#/components/parameters/FilterSourcesBlocklist"
        - $ref: "#/components/parameters/FilterTitleFulltext"
        - $ref: "#/components/parameters/FilterAuthorsFulltext"
        - $ref: "#/components/parameters/FilterCategory"
        - $ref: "#/components/parameters/FilterPublishedAfter"
        - $ref: "#/components/parameters/FilterPublishedBefore"
      responses:
        "200":
          description: RSS feed of alignment research articles
          content:
            text/xml:
              schema:
                type: string
                description: RSS 2.0 XML feed
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Authentication via Auth0 JWT or API token.

        - **Auth0 JWT**: `Bearer auth0|<jwt_token>`
        - **API Token**: `Bearer user_api|<token_hex>`

        Some endpoints (token management) require Auth0 authentication only.

  parameters:
    Page:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: page_size
      in: query
      description: Number of articles per page
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Sort:
      name: sort
      in: query
      description: |
        Comma-separated list of fields to sort by. Append `_desc` for descending order.
        Valid fields: `published_at`, `authors`, `source`, `title`.
        Example: `published_at_desc,source`
      schema:
        type: string
        example: published_at_desc
    ArticleId:
      name: article_id
      in: path
      required: true
      description: Article hash ID
      schema:
        type: string
    FilterCategory:
      name: filter_category
      in: query
      description: |
        Filter by LLM-assigned category. Current categories are listed in the
        schema enum; more may be added over time.
      schema:
        type: string
        enum:
          - Interpretability
          - Safety Techniques
          - Governance & Policy
          - Deception & Misalignment
          - AI Capabilities & Behavior
          - Risks & Strategy
          - Forecasting
          - AI & Society
          - Field Building
          - Other
        example: Interpretability
    FilterSourcesAllowlist:
      name: filter_sources_allowlist
      in: query
      description: Comma-separated list of source names to include
      schema:
        type: string
        example: arxiv,lesswrong
    FilterSourcesBlocklist:
      name: filter_sources_blocklist
      in: query
      description: Comma-separated list of source names to exclude
      schema:
        type: string
        example: youtube
    FilterTitleFulltext:
      name: filter_title_fulltext
      in: query
      description: Full-text search in article titles
      schema:
        type: string
    FilterAuthorsFulltext:
      name: filter_authors_fulltext
      in: query
      description: Full-text search in article authors
      schema:
        type: string
    FilterPublishedAfter:
      name: filter_published_after
      in: query
      description: Include only articles published after this date
      schema:
        type: string
        format: date-time
        example: "2024-01-01T00:00:00Z"
    FilterPublishedBefore:
      name: filter_published_before
      in: query
      description: Include only articles published before this date
      schema:
        type: string
        format: date-time
        example: "2024-12-31T23:59:59Z"

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: API token authentication not allowed for this endpoint
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
    NotFound:
      description: Article not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Article:
      description: An alignment research article with metadata and optional user interaction state.
      type: object
      required:
        - hash_id
        - title
        - link
        - source
      example:
        hash_id: "8f14e45fceea167a5a36dedd4bea2543"
        title: "Scaling Monosemanticity: Extracting Interpretable Features from Claude 3 Sonnet"
        link: "https://arxiv.org/abs/2401.12345"
        text_start: "We apply sparse autoencoders to extract interpretable features..."
        authors: "Jane Smith, John Doe"
        source: "arxiv"
        published_at: "2024-01-15T10:30:00Z"
        summary: "This paper introduces a method for extracting interpretable features from large language models."
        key_points: ["Introduces a new interpretability method", "Demonstrates scaling to large models"]
        category: "Interpretability"
        thumbnail_url: "https://example.com/thumbnail.jpg"
      properties:
        hash_id:
          type: string
          description: Unique identifier for the article
          example: 8f14e45fceea167a5a36dedd4bea2543
        title:
          type: string
          description: Article title
          example: "Scaling Monosemanticity: Extracting Interpretable Features from Claude 3 Sonnet"
        link:
          type: string
          format: uri
          description: URL to the original article
          example: https://arxiv.org/abs/2401.12345
        text_start:
          type: string
          description: Preview text (first ~500 characters of the article)
          example: "We apply sparse autoencoders to extract interpretable features..."
        authors:
          type: string
          description: Comma-separated list of authors
          example: "Jane Smith, John Doe"
        source:
          type: string
          description: Source of the article
          example: arxiv
        published_at:
          type: string
          format: date-time
          nullable: true
          description: Publication date
          example: "2024-01-15T10:30:00Z"
        have_read:
          type: boolean
          description: Whether the authenticated user has marked this as read (only present when authenticated)
          example: true
        thumbs_up:
          type: boolean
          description: Whether the authenticated user has given this a thumbs up (only present when authenticated)
          example: false
        summary:
          type: string
          description: LLM-generated 1-3 sentence summary
          example: "This paper introduces a method for extracting interpretable features from large language models using sparse autoencoders."
        key_points:
          type: array
          items:
            type: string
          description: LLM-generated key takeaways (3-5 points)
          example: ["Introduces a new interpretability method", "Demonstrates scaling to large models"]
        implication:
          type: string
          description: LLM-generated implication for AI alignment
          example: "Advances the ability to understand and verify model internals, which is crucial for alignment."
        category:
          type: string
          description: |
            LLM-assigned category. Current categories: Interpretability,
            Safety Techniques, Governance & Policy, Deception & Misalignment,
            AI Capabilities & Behavior, Risks & Strategy, Forecasting,
            AI & Society, Field Building, Other.
            More may be added over time.
          example: "Interpretability"
        thumbnail_url:
          type: string
          format: uri
          description: URL to a thumbnail image for the article, when available
          example: "https://img.youtube.com/vi/dQw4w9WgXcQ/mqdefault.jpg"
        thumbs_down:
          type: boolean
          description: Whether the authenticated user has given this a thumbs down (only present when authenticated)
          example: false

    ArticlesListResponse:
      description: Paginated list of articles with metadata.
      type: object
      required:
        - data
        - metadata
      example:
        data:
          - hash_id: "8f14e45fceea167a5a36dedd4bea2543"
            title: "Scaling Monosemanticity"
            link: "https://arxiv.org/abs/2401.12345"
            source: "arxiv"
        metadata: {}
      properties:
        data:
          type: array
          description: Array of articles
          items:
            $ref: "#/components/schemas/Article"
        metadata:
          type: object
          description: Response metadata (currently empty, reserved for future use)

    ApiToken:
      description: An API token for programmatic access to the feed.
      type: object
      required:
        - id
        - prefix
        - created_at
        - revoked
      properties:
        id:
          type: string
          format: uuid
          description: Token UUID
        prefix:
          type: string
          description: First 8 characters of the token for identification
          example: user_api
        name:
          type: string
          description: Optional user-provided name for the token
          example: "My CLI token"
        created_at:
          type: string
          format: date-time
          description: When the token was created
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: When the token was last used (null if never used)
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When the token expires (null if no expiration)
        revoked:
          type: boolean
          description: Whether the token has been revoked

    ApiTokenListResponse:
      description: List of API tokens for the authenticated user.
      type: object
      required:
        - data
      example:
        data:
          - id: "550e8400-e29b-41d4-a716-446655440000"
            prefix: "user_api"
            name: "My CLI token"
            created_at: "2024-06-01T12:00:00Z"
            revoked: false
      properties:
        data:
          type: array
          description: Array of API tokens
          items:
            $ref: "#/components/schemas/ApiToken"

    CreateApiTokenRequest:
      description: Request body for creating a new API token.
      type: object
      properties:
        name:
          type: string
          description: Optional name for the token
          example: "My CLI token"

    CreateApiTokenResponse:
      description: Response after successfully creating an API token, including the full token value.
      type: object
      required:
        - id
        - token
        - prefix
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the created token
          example: "550e8400-e29b-41d4-a716-446655440000"
        token:
          type: string
          description: Full token value (only returned at creation time)
          example: "user_api|a1b2c3d4e5f6..."
        prefix:
          type: string
          description: Token prefix for identification
          example: user_api

    SemanticSearchRequest:
      description: Request body for semantic article search.
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Text to find semantically similar articles for
          maxLength: 102400
          example: "Interpretability methods for large language models"
        limit:
          type: integer
          description: Maximum number of articles to return
          minimum: 1
          maximum: 100
          default: 10

    ForbiddenError:
      description: Error response for forbidden actions (e.g. API token used on token management endpoints).
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable explanation of why access is forbidden
          example: "This endpoint cannot be accessed with an API token."

    Error:
      description: Error response returned by the API.
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: "invalid page parameter: must be >= 1"