reqistry-dev Discover API

openapi: 3.2.0
info:
  title: Public APIs — Mobile Client Discover API
  description: 'API reference for the Public APIs Flutter mobile app. Includes anonymous device auth, email/password account linking, profile management, bookmarks, folders, discovery, categories, search, and legacy JSON endpoints.


    ## Authentication


    Bearer-protected endpoints require:


    ```

    Authorization: Bearer

    ```


    Tokens are obtained via `POST /v1/auth/anonymous` or `POST /v1/auth/login-email`.


    Public endpoints (no token required): `POST /submit`, `POST /v1/apis` (auth optional, enables submission attribution), `POST /v1/auth/anonymous`, `POST /v1/auth/refresh`, `POST /v1/auth/revoke`, `POST /v1/auth/login-email`, `GET /v1/recently-added`, `GET /v1/recommend` (auth optional, personalizes with bookmarks), `GET /v1/apis/{slug}`, `GET /v1/apis/{id}/alternatives`, `GET /v1/trust-scores/{id}`, `GET /v1/apis/compare`, `GET /v1/change-feed`, `GET /v1/use-case-collections`, categories (unversioned and `/v1` aliases), `GET /search`, `GET /metadata`, `POST /track`, and `POST /admin/v1/contact-messages`. Every other `/v1/*` operation requires a Bearer token.


    ## Account Types

    - **Anonymous**: Device-only, no email. Data tied to device fingerprint.

    - **Email-linked**: Has email + password. Can login from any device. Data merges on link.


    ## Token Lifecycle

    - **Access token**: 15 minutes, used for API requests

    - **Refresh token**: 30 days, used to rotate access tokens

    - Refreshing a token invalidates the old one (single-use rotation)

    - Revoking deactivates all tokens for a device'
  version: 1.0.0
  contact:
    name: Public APIs
    url: '---'
servers:
- url: http://localhost:4000
  description: Local development
- url: '---'
  description: Production
tags:
- name: Discover
  description: API discovery — recently added, recommendations
paths:
  /v1/recently-added:
    get:
      tags:
      - Discover
      summary: Recently added APIs
      description: Returns the latest published APIs in the legacy flat item format. Ordered by creation date descending.
      operationId: getRecentlyAdded
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Number of APIs to return
      responses:
        '200':
          description: Recently added APIs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentlyAddedResponse'
  /v1/recommend:
    get:
      tags:
      - Discover
      summary: Personalized recommendations
      description: 'Returns API recommendations. If a valid Bearer token is provided and the user has bookmarks, returns personalized results scored by shared category, auth type, API type, pricing type, and description keywords with the user''s bookmarked APIs. If no bookmarks or no token, returns random APIs.


        Results are in the legacy recommendation format.'
      operationId: getPersonalizedRecommend
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        description: Number of recommendations
      security:
      - bearerAuth: []
      - {}
      responses:
        '200':
          description: Recommendations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendResponse'
components:
  schemas:
    LegacyApiItem:
      type: object
      description: Legacy API item format (from discovery or search results)
      properties:
        id:
          type: string
          description: API UUID
        slug:
          type: string
          description: Stable URL slug for this API. Use this when building /v1/apis/{slug} links instead of deriving from name.
        name:
          type: string
        description:
          type: string
        auth:
          type: string
          description: Auth type name
        https:
          type: string
          description: 'HTTPS support as string: ''true'' or ''false'''
        cors:
          type: string
          description: 'CORS status: Yes, No, Unknown'
        link:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: Custom image URL set in the dashboard
        category:
          type: string
        apiType:
          type: string
          description: 'API protocol: REST, GraphQL, etc.'
        pricing:
          type: string
          description: 'Pricing type: Free, Freemium, Paid'
        rateLimit:
          type: string
        documentation:
          type: string
          format: uri
        isAlive:
          type: boolean
        responseTime:
          type: number
          description: Response time in ms, -1 if dead
        statusCode:
          type: integer
          nullable: true
        lastChecked:
          type: string
          format: date-time
    LegacyRecommendationItem:
      type: object
      description: Legacy recommendation item format
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        auth:
          type: string
        https:
          type: boolean
        cors:
          type: boolean
        link:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: Custom image URL set in the dashboard
        categoryId:
          type: string
          description: Category name (not ID)
        pricing:
          type: string
        alive:
          type: boolean
        slug:
          type: string
          description: Stable URL slug for this API. Use this when building detail links.
    RecommendResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LegacyRecommendationItem'
    RecentlyAddedResponse:
      type: object
      properties:
        count:
          type: integer
        total:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/LegacyApiItem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Anonymous device access token from POST /v1/auth/anonymous