openapi: 3.0.3
info:
  title: Phraseanet API (v1)
  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: Account
    description: The authenticated user (me) and access rights.
  - name: Databoxes
    description: Databoxes, their collections, status structure, and metadata structure.
  - name: Search
    description: Elasticsearch-backed search across records and stories.
  - name: Records
    description: Individual media records (assets) within a databox.
  - name: Metadata
    description: Record captions, metadata values, and status flags.
  - name: Stories
    description: Records that group other records.
  - name: Baskets
    description: User-curated working sets of records.
  - name: Feeds
    description: Published feeds and their entries.
  - name: Quarantine
    description: Items awaiting validation before entering a collection.
paths:
  /me:
    get:
      operationId: getMe
      tags:
        - Account
      summary: Get the authenticated user
      description: >-
        Returns the authenticated user (the "me" resource), including profile
        details, collection access rights, field access, and sub-definition
        access.
      responses:
        '200':
          description: The authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /databoxes/list:
    get:
      operationId: listDataboxes
      tags:
        - Databoxes
      summary: List databoxes
      description: Returns the databoxes available to the authenticated application.
      responses:
        '200':
          description: A list of databoxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /databoxes/{databox_id}/collections:
    get:
      operationId: listDataboxCollections
      tags:
        - Databoxes
      summary: List collections of a databox
      description: >-
        Returns the collections available on the specified databox, each with
        base_id, collection_id, name, and record count.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
      responses:
        '200':
          description: A list of collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /databoxes/{databox_id}/status:
    get:
      operationId: getDataboxStatus
      tags:
        - Databoxes
      summary: Get databox status structure
      description: Returns the status-bit structure defined on the databox.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
      responses:
        '200':
          description: The status structure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /databoxes/{databox_id}/metadatas:
    get:
      operationId: getDataboxMetadatas
      tags:
        - Databoxes
      summary: Get databox metadata structure
      description: >-
        Returns the metadata-field structure of the databox that drives record
        captions and metadata values.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
      responses:
        '200':
          description: The metadata structure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /databoxes/{databox_id}/termsOfUse:
    get:
      operationId: getDataboxTermsOfUse
      tags:
        - Databoxes
      summary: Get databox terms of use
      description: Returns the terms of use associated with the databox.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
      responses:
        '200':
          description: The terms of use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /search:
    post:
      operationId: search
      tags:
        - Search
      summary: Search records and stories
      description: >-
        Returns the records (and stories) matching a query. Filters include
        databox and collection ids, status, record type, date range, offset, and
        per-page limits. Backed by Elasticsearch.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Matching records with facets and paging metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /records/add:
    post:
      operationId: addRecord
      tags:
        - Records
      summary: Add a record
      description: >-
        Uploads a new media file into a collection, creating a record (or placing
        it in quarantine when validation is required).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                base_id:
                  type: integer
                  description: Destination collection base_id.
                file:
                  type: string
                  format: binary
                  description: The media file to upload.
      responses:
        '200':
          description: The created record or quarantine item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}:
    get:
      operationId: getRecord
      tags:
        - Records
      summary: Get a record
      description: Returns a single record identified by its databox and record id.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: The record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /records/{databox_id}/{record_id}/embed:
    get:
      operationId: getRecordEmbed
      tags:
        - Records
      summary: Get record sub-definitions
      description: >-
        Returns the embedded sub-definitions (thumbnail, preview, document, and
        other resolutions) generated for a record.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: The record sub-definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/related:
    get:
      operationId: getRecordRelated
      tags:
        - Records
      summary: Get related records
      description: Returns baskets and stories that reference this record.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: Related baskets and stories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/setcollection:
    post:
      operationId: setRecordCollection
      tags:
        - Records
      summary: Move a record to another collection
      description: Moves a record to a different collection within reach of the user.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                base_id:
                  type: integer
                  description: Destination collection base_id.
      responses:
        '200':
          description: The updated record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /records/{databox_id}/{record_id}/delete:
    post:
      operationId: deleteRecord
      tags:
        - Records
      summary: Delete a record
      description: Permanently deletes a record from its databox.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/RecordId'
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /stories/add:
    post:
      operationId: addStory
      tags:
        - Stories
      summary: Create a story
      description: Creates a new story (a record that groups other records).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                base_id:
                  type: integer
      responses:
        '200':
          description: The created story.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /stories/{databox_id}/{story_id}:
    get:
      operationId: getStory
      tags:
        - Stories
      summary: Get a story
      description: Returns a single story and its child records.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/StoryId'
      responses:
        '200':
          description: The story.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /stories/{databox_id}/{story_id}/addrecords:
    post:
      operationId: addRecordsToStory
      tags:
        - Stories
      summary: Add records to a story
      description: Adds one or more records to a story.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/StoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: The updated story.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /stories/{databox_id}/{story_id}/delrecords:
    post:
      operationId: removeRecordsFromStory
      tags:
        - Stories
      summary: Remove records from a story
      description: Removes one or more records from a story.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/StoryId'
      responses:
        '200':
          description: The updated story.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /stories/{databox_id}/{story_id}/setcover:
    post:
      operationId: setStoryCover
      tags:
        - Stories
      summary: Set story cover
      description: Sets the cover image of a story from one of its child records.
      parameters:
        - $ref: '#/components/parameters/DataboxId'
        - $ref: '#/components/parameters/StoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                record_id:
                  type: integer
      responses:
        '200':
          description: The updated story.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/list:
    get:
      operationId: listBaskets
      tags:
        - Baskets
      summary: List baskets
      description: Returns the baskets owned by or shared with the authenticated user.
      responses:
        '200':
          description: A list of baskets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/add:
    post:
      operationId: addBasket
      tags:
        - Baskets
      summary: Create a basket
      description: Creates a new basket, optionally seeded with records.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The created basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/{basket_id}/content:
    get:
      operationId: getBasketContent
      tags:
        - Baskets
      summary: Get basket content
      description: Returns the records contained in a basket.
      parameters:
        - $ref: '#/components/parameters/BasketId'
      responses:
        '200':
          description: The basket content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/{basket_id}/setname:
    post:
      operationId: setBasketName
      tags:
        - Baskets
      summary: Rename a basket
      description: Sets the name of a basket.
      parameters:
        - $ref: '#/components/parameters/BasketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: The updated basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/{basket_id}/setdescription:
    post:
      operationId: setBasketDescription
      tags:
        - Baskets
      summary: Set basket description
      description: Sets the description of a basket.
      parameters:
        - $ref: '#/components/parameters/BasketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
      responses:
        '200':
          description: The updated basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /baskets/{basket_id}/delete:
    post:
      operationId: deleteBasket
      tags:
        - Baskets
      summary: Delete a basket
      description: Deletes a basket.
      parameters:
        - $ref: '#/components/parameters/BasketId'
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /feeds/list:
    get:
      operationId: listFeeds
      tags:
        - Feeds
      summary: List feeds
      description: Returns the published feeds visible to the authenticated user.
      responses:
        '200':
          description: A list of feeds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /feeds/{feed_id}/content:
    get:
      operationId: getFeedContent
      tags:
        - Feeds
      summary: Get feed content
      description: Returns the entries of a single feed with their records.
      parameters:
        - name: feed_id
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: The feed entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /feeds/aggregated/content:
    get:
      operationId: getAggregatedFeedContent
      tags:
        - Feeds
      summary: Get aggregated feed content
      description: Returns an aggregated view of entries across all visible feeds.
      parameters:
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: The aggregated feed entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /quarantine/list:
    get:
      operationId: listQuarantine
      tags:
        - Quarantine
      summary: List quarantine items
      description: Lists items held in quarantine awaiting validation.
      responses:
        '200':
          description: A list of quarantine items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /quarantine/{quarantine_item_id}:
    get:
      operationId: getQuarantineItem
      tags:
        - Quarantine
      summary: Get a quarantine item
      description: Returns a single quarantine item by id.
      parameters:
        - name: quarantine_item_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The quarantine item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  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.
  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
    StoryId:
      name: story_id
      in: path
      required: true
      description: The story identifier within the databox.
      schema:
        type: integer
    BasketId:
      name: basket_id
      in: path
      required: true
      description: The basket identifier.
      schema:
        type: integer
    Offset:
      name: offset_start
      in: query
      required: false
      description: Zero-based offset of the first result to return.
      schema:
        type: integer
        default: 0
    PerPage:
      name: per_page
      in: query
      required: false
      description: Maximum number of results per page.
      schema:
        type: integer
        default: 10
  responses:
    Unauthorized:
      description: Missing or invalid OAuth2 token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
  schemas:
    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
    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.
    SearchRequest:
      type: object
      description: Search parameters.
      properties:
        query:
          type: string
          description: The full-text query string.
        bases:
          type: array
          description: Databox / collection ids to search within.
          items:
            type: integer
        offset_start:
          type: integer
          default: 0
        per_page:
          type: integer
          default: 10
        search_type:
          type: integer
          description: 0 for records, 1 for stories.
        record_type:
          type: string
          description: Filter by record type (image, video, audio, document).
        status:
          type: object
          additionalProperties:
            type: boolean
    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