openapi: 3.0.3
info:
  title: Phraseanet API (v1) Account Metadata API
  description: Phraseanet is an open-source (GPL-v3) Digital Asset Management (DAM) platform by Alchemy. This document models the documented Phraseanet REST API v1, which is secured with OAuth2 and covers records, databoxes and collections, metadata, search, stories, baskets, and feeds. Phraseanet is self-hosted, so the API is served from each organization's own instance - there is no single public shared endpoint. Replace the server host with your Phraseanet instance. All responses are wrapped in an object with `meta` and `response` fields and are JSON by default. A newer API v3 is published on SwaggerHub (alchemy-fr/phraseanet.api.v3). Endpoints here are grounded in the public v1 route documentation; request and response bodies are honestly modeled and should be confirmed against your Phraseanet version.
  version: 1.5.0
  contact:
    name: Alchemy - Phraseanet
    url: https://www.phraseanet.com/
  license:
    name: GPL-3.0
    url: https://github.com/alchemy-fr/Phraseanet/blob/4.1/LICENSE
servers:
- url: https://{host}/api/v1
  description: Phraseanet instance (self-hosted)
  variables:
    host:
      default: your-phraseanet-instance
      description: Hostname of your Phraseanet installation.
security:
- oauth2: []
- oauthTokenParam: []
tags:
- name: Metadata
  description: Record captions, metadata values, and status flags.
paths:
  /records/{databox_id}/{record_id}/caption:
    get:
      operationId: getRecordCaption
      tags:
      - Metadata
      summary: Get record caption
      description: Returns the caption (display metadata) of a record.
      parameters:
      - $ref: '#/components/parameters/DataboxId'
      - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: The record caption.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/metadatas:
    get:
      operationId: getRecordMetadatas
      tags:
      - Metadata
      summary: Get record metadatas
      description: Returns the raw metadata values of a record.
      parameters:
      - $ref: '#/components/parameters/DataboxId'
      - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: The record metadatas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/setmetadatas:
    post:
      operationId: setRecordMetadatas
      tags:
      - Metadata
      summary: Set record metadatas
      description: Adds or modifies metadata on a record. Each entry references a metadata structure id and a value.
      parameters:
      - $ref: '#/components/parameters/DataboxId'
      - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMetadatasRequest'
      responses:
        '200':
          description: The updated record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/status:
    get:
      operationId: getRecordStatus
      tags:
      - Metadata
      summary: Get record status
      description: Returns the status-bit values of a record.
      parameters:
      - $ref: '#/components/parameters/DataboxId'
      - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: The record status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/setstatus:
    post:
      operationId: setRecordStatus
      tags:
      - Metadata
      summary: Set record status
      description: Sets status-bit values on a record.
      parameters:
      - $ref: '#/components/parameters/DataboxId'
      - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: object
                  additionalProperties:
                    type: boolean
      responses:
        '200':
          description: The updated record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  parameters:
    DataboxId:
      name: databox_id
      in: path
      required: true
      description: The databox identifier.
      schema:
        type: integer
    RecordId:
      name: record_id
      in: path
      required: true
      description: The record identifier within the databox.
      schema:
        type: integer
  schemas:
    Envelope:
      type: object
      description: Standard Phraseanet response wrapper. Every response contains a meta object and a response payload.
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        response:
          type: object
          description: The endpoint-specific payload.
    SetMetadatasRequest:
      type: object
      description: Metadata values to apply to a record.
      properties:
        metadatas:
          type: array
          items:
            type: object
            properties:
              meta_struct_id:
                type: integer
                description: The databox metadata structure id.
              value:
                type: string
              meta_id:
                type: integer
                nullable: true
              append:
                type: boolean
                default: false
    Meta:
      type: object
      description: Response envelope metadata.
      properties:
        api_version:
          type: string
        request:
          type: string
        response_time:
          type: string
        http_code:
          type: integer
        error_type:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2. Register an application in Phraseanet to obtain a client id and secret.
      flows:
        authorizationCode:
          authorizationUrl: https://your-phraseanet-instance/api/oauthv2/authorize
          tokenUrl: https://your-phraseanet-instance/api/oauthv2/token
          scopes: {}
    oauthTokenParam:
      type: apiKey
      in: query
      name: oauth_token
      description: OAuth2 access token passed as the oauth_token query parameter.