Inboxy Feeds API

openapi: 3.2.0
info:
  title: inboxy Feeds API
  version: 0.3.0
  summary: Read + manage your inboxy.net inbox programmatically.
  description: 'REST surface over the inboxy alias inbox. Mint aliases, list/search/read

    messages, fetch attachments, manage your API keys, and emit user-initiated

    mail under one of your aliases.


    Mail-emitting paths (`POST /v1/messages/{id}/reply`, `POST /v1/mail/send`,

    `POST /v1/mail/invite`) are recipient-locked and alias-locked server-side:

    the `From:` is always one of the caller''s `@inboxy.net` aliases, the

    recipient is validated against per-user caps and the abuse rules in

    `packages/reply`, and every external message carries the mandatory

    inboxy attribution footer. There is no arbitrary-`From:` send path.


    All endpoints require a bearer API key created from the inboxy.net web UI

    at `/account/keys` (mint is gated by step-up and lives only on the web — there

    is no API-channel mint). Pass it as `Authorization: Bearer ik_…`.


    The signed-token attachment download URLs (`/v1/attachments/{token}/download`,

    `/v1/messages/raw/{token}/download`) are public-by-token — they intentionally

    bypass bearer auth and are not listed here. Obtain them via the JSON

    endpoints below.'
  contact:
    name: inboxy
    url: https://inboxy.net
  license:
    name: Proprietary
servers:
- url: https://api.inboxy.net
  description: Production
security:
- bearerAuth: []
tags:
- name: Feeds
  description: RSS / Atom feed subscriptions.
paths:
  /v1/feeds:
    get:
      tags:
      - Feeds
      summary: List your feed subscriptions
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - error
          - inactive
      responses:
        '200':
          description: Feeds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  feeds:
                    type: array
                    items:
                      $ref: '#/components/schemas/Feed'
      operationId: getV1Feeds
      x-operation-id-source: derived
    post:
      tags:
      - Feeds
      summary: Subscribe to a feed by URL
      description: Requires `manage` scope. The same source URL is shared across all subscribers (one fetch serves everyone) — but your label and read-state stay private.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedCreate'
      responses:
        '201':
          description: Subscribed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Already subscribed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1Feeds
      x-operation-id-source: derived
  /v1/feeds/{id}:
    get:
      tags:
      - Feeds
      summary: Get one subscription
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Feed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1FeedsById
      x-operation-id-source: derived
    patch:
      tags:
      - Feeds
      summary: Update a subscription's label
      description: Requires `manage` scope.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedPatch'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  label:
                    type:
                    - string
                    - 'null'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: patchV1FeedsById
      x-operation-id-source: derived
    delete:
      tags:
      - Feeds
      summary: Unsubscribe from a feed
      description: Requires `manage` scope. Other subscribers (if any) keep the feed; your read-state for it is deleted.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Unsubscribed.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteV1FeedsById
      x-operation-id-source: derived
  /v1/feeds/{id}/refresh:
    post:
      tags:
      - Feeds
      summary: Trigger a manual re-poll of one feed
      description: Requires `manage` scope. Returns immediately; new articles land within ~30s. The poll benefits every subscriber to the underlying source.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  queued:
                    type: boolean
                    enum:
                    - true
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1FeedsByIdRefresh
      x-operation-id-source: derived
  /v1/feeds/{id}/articles:
    get:
      tags:
      - Feeds
      summary: List articles in one feed, newest first
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: unread
        in: query
        schema:
          type: boolean
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 25
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Page of articles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesPage'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1FeedsByIdArticles
      x-operation-id-source: derived
  /v1/feeds/{id}/articles/count:
    get:
      tags:
      - Feeds
      summary: Count articles in one feed
      description: Returns `{ total, unread }` for the subscription.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Aggregate counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResult'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1FeedsByIdArticlesCount
      x-operation-id-source: derived
components:
  schemas:
    FeedCreate:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
        label:
          type: string
          maxLength: 64
    ArticleMeta:
      type: object
      required:
      - id
      - feed_id
      - read
      - fetched_at
      properties:
        id:
          type: string
          format: uuid
        feed_id:
          type: string
          format: uuid
          description: The subscription id this article surfaces through.
        title:
          type:
          - string
          - 'null'
        link:
          type:
          - string
          - 'null'
          format: uri
        author:
          type:
          - string
          - 'null'
        published_at:
          type:
          - integer
          - 'null'
        fetched_at:
          type: integer
        read:
          type: boolean
    CountResult:
      type: object
      required:
      - total
      - unread
      description: Aggregate over a filtered set. `total` counts every matching row; `unread` is the subset that is still unread.
      properties:
        total:
          type: integer
          minimum: 0
        unread:
          type: integer
          minimum: 0
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - gone
          - rate_limited
          - internal
          - invalid_token
          - blocked
        message:
          type: string
    ArticlesPage:
      type: object
      required:
      - articles
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/ArticleMeta'
        next_cursor:
          type:
          - string
          - 'null'
    FeedPatch:
      type: object
      required:
      - label
      properties:
        label:
          type:
          - string
          - 'null'
          maxLength: 64
    Feed:
      type: object
      required:
      - id
      - url
      - status
      - subscribed_at
      - unread
      properties:
        id:
          type: string
          format: uuid
          description: Per-user subscription id. Use this everywhere — the shared feed_sources id is never exposed.
        label:
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        homepage_link:
          type:
          - string
          - 'null'
        language:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - error
          - inactive
        last_polled_at:
          type:
          - integer
          - 'null'
          description: Unix seconds.
        last_error:
          type:
          - string
          - 'null'
        subscribed_at:
          type: integer
        total:
          type: integer
          minimum: 0
          description: Total articles in this feed (across all subscribers).
        unread:
          type: integer
          description: Your unread article count.
  responses:
    NotFound:
      description: No matching resource owned by the caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Token lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ik_…
      description: Static API key. Three scopes — `read` (everything except mutations), `manage` (mutations other than sending) and `send` (`/v1/mail/send`, replies, invites). Mint at https://inboxy.net/account/keys (the web UI gates mint with step-up; there is no API-channel mint).