openapi: 3.2.0
info:
  title: Pexafy Facets API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged facets across 2 of this provider''s published API definitions: pexafy-openapi-v1.3.0.json, pexafy-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.pexafy.com/api/v1
  description: Production
- url: https://api.pexafy.com
  description: Production
tags:
- name: facets
  description: What the filters accept.
paths:
  /facets/colors:
    get:
      operationId: listColors
      tags:
      - facets
      summary: Allowed colour filters
      description: The colour names color_name accepts.
      responses:
        '200':
          description: The allowed values and how much of the catalogue each covers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetEnvelope'
              example:
                success: true
                data:
                - value: blue
                  label: Blue
                  count: 1840221
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /facets/sources:
    get:
      operationId: listSources
      tags:
      - facets
      summary: Indexed libraries
      description: The libraries source accepts. This list grows.
      responses:
        '200':
          description: The allowed values and how much of the catalogue each covers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetEnvelope'
              example:
                success: true
                data:
                - value: blue
                  label: Blue
                  count: 1840221
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /facets/orientations:
    get:
      operationId: listOrientations
      tags:
      - facets
      summary: Allowed orientations
      description: The values orientation accepts.
      responses:
        '200':
          description: The allowed values and how much of the catalogue each covers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetEnvelope'
              example:
                success: true
                data:
                - value: blue
                  label: Blue
                  count: 1840221
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /facets/licenses:
    get:
      operationId: listLicenses
      tags:
      - facets
      summary: Allowed licence families
      description: The values license_type accepts, with what each permits.
      responses:
        '200':
          description: The allowed values and how much of the catalogue each covers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetEnvelope'
              example:
                success: true
                data:
                - value: blue
                  label: Blue
                  count: 1840221
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /facets/photographers/suggest:
    get:
      operationId: suggestPhotographers
      tags:
      - facets
      summary: Autocomplete a photographer name
      parameters:
      - name: q
        in: query
        description: Prefix of a username or a display name.
        schema:
          type: string
          minLength: 1
          maxLength: 80
        required: true
      - name: limit
        in: query
        description: How many suggestions to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      responses:
        '200':
          description: Matching photographers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotographerEnvelope'
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '422':
          description: A parameter was rejected before the search ran.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: validation_failed
                  message: A parameter was rejected before the search ran.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /facets/photographers/{username}:
    get:
      operationId: getPhotographer
      tags:
      - facets
      summary: One photographer
      description: Returns a list because one username can exist in more than one upstream library, and they are different people often enough to matter.
      parameters:
      - name: username
        in: path
        description: Photographer username.
        schema:
          type: string
          maxLength: 120
        required: true
      responses:
        '200':
          description: Everyone holding that username.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotographerEnvelope'
        '401':
          description: The API key is missing, malformed or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: unauthenticated
                  message: The API key is missing, malformed or revoked.
                  request_id: req_01J8Z3
        '404':
          description: No such resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: not_found
                  message: No such resource.
                  request_id: req_01J8Z3
        '429':
          description: Too many requests, or the plan quota is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: rate_limited
                  message: Too many requests, or the plan quota is exhausted.
                  request_id: req_01J8Z3
      security:
      - apiKey: []
    servers:
    - url: https://api.pexafy.com/api/v1
      description: Production
  /api/v1/facets/colors:
    get:
      tags:
      - facets
      summary: List colors
      description: 'List the dominant colors you can filter photos by. Each entry has a `name` (pass it as `color_name` when searching) and its `hex` code — handy for building a color picker.


        > **Facets** are simply the lists of values that the search filters accept. Read them once to populate your filter UI, then feed the chosen value back into **Search photos**.'
      operationId: facet_colors_api_v1_facets_colors_get
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ColorsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
  /api/v1/facets/sources:
    get:
      tags:
      - facets
      summary: List sources
      description: List the photo providers available in the library (for example Unsplash, Pexels, Pixabay). Use a `name` as the `source` filter when searching. Each entry also includes a `license_url` pointing to that provider's licensing terms.
      operationId: facet_sources_api_v1_facets_sources_get
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
  /api/v1/facets/orientations:
    get:
      tags:
      - facets
      summary: List orientations
      description: List the available photo shapes — `landscape`, `portrait` and `square`. Use a `name` as the `orientation` filter when searching.
      operationId: facet_orientations_api_v1_facets_orientations_get
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrientationsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
  /api/v1/facets/licenses:
    get:
      tags:
      - facets
      summary: List license types
      description: List the license types available in the library. Use a `name` as the `license_type` filter when searching to keep only photos you are allowed to use in a given way.
      operationId: facet_licenses_api_v1_facets_licenses_get
      parameters: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicensesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
  /api/v1/facets/photographers/suggest:
    get:
      tags:
      - facets
      summary: Search photographers
      description: Autocomplete photographer names as the user types. Pass a partial name or username in `q` and get back the best-matching photographers, the most prolific first. Use a returned `username` as the `photographer` filter when searching.
      operationId: suggest_photographers_api_v1_facets_photographers_suggest_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 100
          description: What the user has typed so far — a partial name or username (1–100 characters).
          title: Q
        description: What the user has typed so far — a partial name or username (1–100 characters).
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
        description: Maximum number of suggestions to return, from 1 to 50. Defaults to 10.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotographersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
  /api/v1/facets/photographers/{username}:
    get:
      tags:
      - facets
      summary: Get a photographer's profiles
      description: Return every profile for a photographer across providers. The same `username` can exist on several sources (Unsplash, Pexels, Pixabay) and may even be different people, so this returns a **list** — one entry per source, each with its own `full_name`, profile `url` and per-source `photos_count`.
      operationId: get_photographer_api_v1_facets_photographers__username__get
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
          title: Username
        description: The photographer's exact username, as returned by the suggest endpoint or found on a photo.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotographerResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.pexafy.com
      description: Production
components:
  schemas:
    Meta:
      type: object
      properties:
        request_id:
          type: string
        took_ms:
          type: number
          description: Server side time, excluding transfer.
    FacetEnvelope:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Facet'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorEnvelope:
      type: object
      required:
      - success
      - error
      description: Every failure uses this shape, whatever the status code.
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: 'Machine readable and stable across versions. Branch on this, not on the message. The set is extensible: treat an unrecognised code as a generic failure of its status class.'
              example: validation_failed
            message:
              type: string
              description: Human readable, not stable.
            request_id:
              type: string
            field:
              type:
              - string
              - 'null'
              description: Which parameter was rejected, when the failure is about one.
    Photographer:
      type: object
      required:
      - username
      properties:
        username:
          type: string
        full_name:
          type:
          - string
          - 'null'
        source:
          $ref: '#/components/schemas/Source'
        url:
          type:
          - string
          - 'null'
          format: uri
        photos_count:
          type: integer
          minimum: 0
      example:
        username: a-photographer
        source: unsplash
        photos_count: 412
    Facet:
      type: object
      required:
      - value
      description: One allowed value of a filter, with how much of the catalogue it covers. Read these rather than hard coding the lists.
      properties:
        value:
          type: string
        label:
          type: string
        count:
          type: integer
          minimum: 0
      example:
        value: blue
        label: Blue
        count: 1840221
    Source:
      type: string
      enum:
      - pexels
      - unsplash
      - pixabay
      - wikimedia
      x-extensible-enum: true
      description: 'Upstream library. Extensible: this list grows as libraries are indexed, so parse it as an open string.'
    PhotographerEnvelope:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Photographer'
        meta:
          $ref: '#/components/schemas/Meta'
      example:
        success: true
        data:
        - username: a-photographer
          source: unsplash
          photos_count: 412
    Meta_2:
      type: object
      properties:
        request_id:
          type: string
          description: Unique id for this request (quote it in support tickets).
        took_ms:
          type: number
          description: Server processing time in milliseconds.
    LicensesResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
    ColorsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              hex:
                type: string
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
    SourcesResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              license_url:
                type:
                - string
                - 'null'
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
    Photographer_2:
      type: object
      properties:
        username:
          type: string
        full_name:
          type:
          - string
          - 'null'
        source:
          type: string
        url:
          type:
          - string
          - 'null'
          format: uri
        photos_count:
          type: integer
    PhotographersResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Photographer_2'
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
    PhotographerResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Photographer_2'
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code (e.g. `MISSING_PARAMS`, `PHOTO_NOT_FOUND`).
        message:
          type: string
          description: Human-readable error message.
        request_id:
          type: string
      required:
      - code
      - message
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OrientationsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
        meta:
          $ref: '#/components/schemas/Meta_2'
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiError'
          - type: 'null'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Send the key as a bearer token. Keys carry scopes; a read scoped key gets a 403 on anything under /collections.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Pass your Pexafy API key in this header.


        Get your API key at [pexafy.com/dashboard/api-keys/create](https://pexafy.com/dashboard/api-keys/create/).'
x-refined-from:
- pexafy-openapi-v1.3.0.json
- pexafy-openapi.json