openapi: 3.0.0 info: description: | This is the documentation of Phraseanet API (v3) version: 1.0.0-oas3 title: Phraseanet API termsOfService: 'http://phraseanet.com/terms/' contact: email: support@alchemy.fr license: name: GNU GPL V3 url: 'https://www.gnu.org/licenses/gpl-3.0.en.html' components: parameters: offsetParam: name: offset in: query description: offset in records count required: false schema: type: integer minimum: 0 default: 0 limitParam: name: limit in: query description: number of results required: false schema: type: integer minimum: 1 maximum: 100 default: 10 sbas_id: name: sbas_id in: path description: ID of the databox required: true schema: type: integer record_id: name: record_id in: path description: ID of the record required: true schema: type: integer paths: /me: get: description: blabla servers: - url: 'https://alpha.preprod.alchemyasp.com/api/v1' responses: '200': description: successful operation default: description: Any error /search: post: tags: - search description: | Fulltext search for records or stories. - pagination: use (offset/limit) OR (page/per_page) parameters: - name: query in: query description: Fulltext query ( = search all) required: false schema: type: string example: dogs OR cats default: '' - name: search_type in: query required: false schema: type: integer enum: - 0 - 1 default: 0 description: | * `0` - search for records * `1` - search for stories - name: page in: query description: 'page number, from 1. Use along with "per_page"' required: false schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: number of results per page. Use along with "page" required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - name: offset in: query description: 'offset in records count, from 0. Use along with "limit"' required: false schema: type: integer minimum: 0 - name: limit in: query description: number of results. Use along with "offset" required: false schema: type: integer minimum: 1 maximum: 100 - name: story_children_limit in: query description: 'For each story in result, include N children' required: false schema: type: integer minimum: 0 maximum: 10 default: '0' - name: include in: query description: Suplemental elements to be included in response required: false schema: type: array uniqueItems: false items: type: string enum: - facets - result.stories.children responses: '200': description: ok content: application/json: schema: type: object properties: meta: type: object properties: api_version: type: string request: type: string response_time: type: string format: date-time http_code: type: integer format: int32 error_type: type: string error_message: type: string response: type: object properties: offset: type: integer description: Pagination offset as passed (or computed from "page/per_page") in request limit: type: integer description: Pagination limit as passed in request count: type: integer description: 'Number of results in this page [0...limit]' total: type: integer description: Total number of results minimum: 1 results: type: object properties: stories: type: array items: allOf: - type: object properties: databox_id: type: integer record_id: type: integer title: type: string original_name: type: string updated_on: type: string format: date-time created_on: type: string format: date-time collection_id: type: integer base_id: type: integer thumbnail: type: object properties: name: type: string permalink: type: object properties: created_on: type: string format: date-time id: type: integer is_activated: type: boolean label: type: string updated_on: type: string format: date-time page_url: type: string download_url: type: string url: type: string height: type: integer width: type: integer filesize: type: integer devices: type: array items: type: string enum: - screen - printer ? player_type: type: string enum: - IMAGE mime_type: type: string substituted: type: boolean created_on: type: string format: date-time updated_on: type: string format: date-time url: type: string url_ttl: type: integer uuid: type: string - type: object properties: children_offset: type: integer description: Children pagination offset ; Always 0 children_limit: type: integer description: Children pagination limit ; Equal to "story_children_limit" passed in request children_count: type: integer description: 'Number of children in "children" array ; [0...limit]' children_total: type: integer description: Total number of -visibles for user- children in this story children: type: array items: type: object items: allOf: - type: object properties: databox_id: type: integer record_id: type: integer title: type: string original_name: type: string updated_on: type: string format: date-time created_on: type: string format: date-time collection_id: type: integer base_id: type: integer thumbnail: type: object properties: name: type: string permalink: type: object properties: created_on: type: string format: date-time id: type: integer is_activated: type: boolean label: type: string updated_on: type: string format: date-time page_url: type: string download_url: type: string url: type: string height: type: integer width: type: integer filesize: type: integer devices: type: array items: type: string enum: - screen - printer ? player_type: type: string enum: - IMAGE mime_type: type: string substituted: type: boolean created_on: type: string format: date-time updated_on: type: string format: date-time url: type: string url_ttl: type: integer uuid: type: string - type: object properties: mime_type: type: string technical_informations: type: array items: type: object properties: name: type: string value: type: string sha256: type: string phrasea_type: type: string enum: - image - video records: type: array items: allOf: - type: object properties: databox_id: type: integer record_id: type: integer title: type: string original_name: type: string updated_on: type: string format: date-time created_on: type: string format: date-time collection_id: type: integer base_id: type: integer thumbnail: type: object properties: name: type: string permalink: type: object properties: created_on: type: string format: date-time id: type: integer is_activated: type: boolean label: type: string updated_on: type: string format: date-time page_url: type: string download_url: type: string url: type: string height: type: integer width: type: integer filesize: type: integer devices: type: array items: type: string enum: - screen - printer ? player_type: type: string enum: - IMAGE mime_type: type: string substituted: type: boolean created_on: type: string format: date-time updated_on: type: string format: date-time url: type: string url_ttl: type: integer uuid: type: string - type: object properties: mime_type: type: string technical_informations: type: array items: type: object properties: name: type: string value: type: string sha256: type: string phrasea_type: type: string enum: - image - video facets: type: array items: type: object properties: name: type: string description: Unique internal name (=key) for the facet example: _base field: type: string description: 'Source field (from db structure). Can be also virtual field like "database" ' example: database values: type: array items: type: object properties: value: type: string description: Human readable value for the value example: Demo raw_value: type: string description: 'Real value, to be used to query' example: db_demo count: type: integer description: Number of items matching this value query: type: string description: Formulated query to search items matching this facet example: 'database:db_demo' default: description: Any (other) error /searchraw: post: tags: - searchraw description: | Fulltext search for records or stories; Returns raw es - pagination: use (offset/limit) OR (page/per_page) parameters: - name: query in: query description: Fulltext query ( = search all) required: false schema: type: string example: dogs OR cats default: '' - name: search_type in: query required: false schema: type: integer enum: - 0 - 1 default: 0 description: | search for records or stories * `0` - search for records * `1` - search for stories - name: page in: query description: 'page number, from 1. Use along with "per_page"' required: false schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: number of results per page. Use along with "page" required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - name: offset in: query description: 'offset in records count, from 0. Use along with "limit"' required: false schema: type: integer minimum: 0 - name: limit in: query description: number of results. Use along with "offset" required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: ok content: application/json: schema: type: object properties: meta: type: object properties: api_version: type: string request: type: string response_time: type: string format: date-time http_code: type: integer format: int32 error_type: type: string error_message: type: string response: type: object properties: results: type: array items: description: Raw response from es search on "record" index/mapping type: object properties: _index: type: string description: ES index example: phraseanet_dxmpcw3y8td68f+h_20201124161735.910647 _type: type: string description: Data type example: record _id: type: string description: unique id of document (sbas_id + "_" + record_id) example: '1_555' _version: type: integer description: auto-increment at each indexation of the document example: 1 _score: type: number description: score of the document related to a whole resultset example: 1 _source: type: object properties: record_id: type: integer collection_id: type: integer uuid: type: string example: dcee40ea-ee26-4d8b-b0c2-d61305b03bc0 flags_bitfield: type: integer sha256: type: string example: 7fad283de349b903c850548cda65cf2d86d24c4e3856cdc2b97e47430494b8c8 original_name: type: string example: 1134340545.jpg mime: type: string example: image/jpeg type: type: string example: image created_on: type: string format: date-time example: '2020-12-07 09:48:01' updated_on: type: string format: date-time example: '2021-01-01 15:30:00' coll_id: type: integer collection_name: type: string example: collection de test witdh: type: integer example: 5616 height: type: integer example: 3744 size: type: integer example: 5618218 base_id: type: integer databox_id: type: integer databox_name: type: string example: db_databox1 record_type: type: string enum: - record - story title: type: object description: 'key->value list, where (key) is the lng, and (value) the title in this lng.' additionalProperties: true example: fr: titre en Français en: title in english '': undefined-lng title ? To be fixed metadata_tags: type: object description: 'key->value list, where (key) is the name of the metadata, and (value) the value.' additionalProperties: true example: Channels: 3 ColorDepth: 8 ColorSpace: 0 FileSize: 5618218 Height: 3744 MimeType: image/jpeg Width: 5616 caption: type: object description: | 'key->value list, where (key) is the field name, and (value) the value(s).' 'nb: mono-valued field value is a 1 element array.' additionalProperties: type: array items: type: string example: Artist: - Bob Title: - Cropped Hand Of Person Holding Computer Mouse Keywords: - Hand - Mouse (computer) caption_all: type: array items: type: string description: | 'all fields values in a single array' example: - Bob - Cropped Hand Of Person Holding Computer Mouse - Hand - Mouse (computer) flags: type: object description: 'key->value list, where (key) is the name of the flag (=status bit), and (value) is the boolean value.' additionalProperties: type: boolean example: public: true color_checked: true embargo: false subdefs: type: object description: 'key->value list, where (key) is the name of the subdef, and (value) is the subdef object.' additionalProperties: type: object example: document: type: object properties: width: 5616 height: 3744 size: 5618218 mime: image/jpeg permalink: 'http://localhost/permalink/v1/2/34/document/1134340545.jpg?token=xrdMnK6peB...' thumbnail: type: object properties: width: 1024 height: 683 size: 20011 mime: image/jpeg permalink: 'http://localhost/permalink/v1/2/34/preview/1134340545.jpg?token=E5aSbXQTmAz...' took: type: integer description: Search duration in msec example: 12 count: type: integer description: 'Number of results in this page [0...limit]' example: 1 total: type: integer description: Total number of results example: 1 facets: type: array items: type: object properties: name: type: string description: Unique internal name (=key) for the facet example: _base field: type: string description: 'Source field (from db structure). Can be also virtual field like "database" ' example: database values: type: array items: type: object properties: value: type: string description: Human readable value for the value example: Demo raw_value: type: string description: 'Real value, to be used to query' example: db_demo count: type: integer description: Number of items matching this value query: type: string description: Formulated query to search items matching this facet example: 'database:db_demo' default: description: Any (other) error '/records/{base_id}': post: tags: - record summary: Creates a record description: 'Creates a single record, including document and/or data.' operationId: createRecord parameters: - name: base_id in: path description: ID of the base required: true schema: type: integer requestBody: content: multipart/form-data: schema: description: to create a record with a file (document) type: object properties: body: description: 'Metadata, status, collection, etc to be set for a record' type: object properties: metadatas: type: array items: type: object properties: field_name: type: string meta_struct_id: type: integer action: type: string enum: - set - add - delete - replace value: type: string status: type: array items: type: object required: - bit - state properties: bit: type: integer minimum: 4 maximum: 31 state: type: boolean file: description: uploaded file type: string format: binary application/json: schema: description: to create a record without file (document) allOf: - description: 'Metadata, status, collection, etc to be set for a record' type: object properties: metadatas: type: array items: type: object properties: field_name: type: string meta_struct_id: type: integer action: type: string enum: - set - add - delete - replace value: type: string status: type: array items: type: object required: - bit - state properties: bit: type: integer minimum: 4 maximum: 31 state: type: boolean responses: '200': description: ok content: application/json: schema: type: object properties: meta: type: object properties: api_version: type: string request: type: string response_time: type: string format: date-time http_code: type: integer format: int32 error_type: type: string error_message: type: string response: allOf: - type: object properties: databox_id: type: integer record_id: type: integer title: type: string original_name: type: string updated_on: type: string format: date-time created_on: type: string format: date-time collection_id: type: integer base_id: type: integer thumbnail: type: object properties: name: type: string permalink: type: object properties: created_on: type: string format: date-time id: type: integer is_activated: type: boolean label: type: string updated_on: type: string format: date-time page_url: type: string download_url: type: string url: type: string height: type: integer width: type: integer filesize: type: integer devices: type: array items: type: string enum: - screen - printer ? player_type: type: string enum: - IMAGE mime_type: type: string substituted: type: boolean created_on: type: string format: date-time updated_on: type: string format: date-time url: type: string url_ttl: type: integer uuid: type: string - type: object properties: mime_type: type: string technical_informations: type: array items: type: object properties: name: type: string value: type: string sha256: type: string phrasea_type: type: string enum: - image - video default: description: Any (other) error '/records/{sbas_id}/{record_id}': get: tags: - record summary: Find record by sbas_id and record_id description: Returns a single record operationId: getRecordById parameters: - name: sbas_id in: path description: ID of the databox required: true schema: type: integer - name: record_id in: path description: ID of the record required: true schema: type: integer responses: '200': description: ok content: application/json: schema: type: object properties: meta: type: object properties: api_version: type: string request: type: string response_time: type: string format: date-time http_code: type: integer format: int32 error_type: type: string error_message: type: string response: allOf: - type: object properties: databox_id: type: integer record_id: type: integer title: type: string original_name: type: string updated_on: type: string format: date-time created_on: type: string format: date-time collection_id: type: integer base_id: type: integer thumbnail: type: object properties: name: type: string permalink: type: object properties: created_on: type: string format: date-time id: type: integer is_activated: type: boolean label: type: string updated_on: type: string format: date-time page_url: type: string download_url: type: string url: type: string height: type: integer width: type: integer filesize: type: integer devices: type: array items: type: string enum: - screen - printer ? player_type: type: string enum: - IMAGE mime_type: type: string substituted: type: boolean created_on: type: string format: date-time updated_on: type: string format: date-time url: type: string url_ttl: type: integer uuid: type: string - type: object properties: mime_type: type: string technical_informations: type: array items: type: object properties: name: type: string value: type: string sha256: type: string phrasea_type: type: string enum: - image - video '404': description: Record not found default: description: Any (other) error '/stories/{sbas_id}/{record_id}/children': get: tags: - story summary: Returns uri of each record (child) contained in the story ; Optional pagination description: Returns children of a story operationId: getStoryChildren parameters: - name: sbas_id in: path description: ID of the databox required: true schema: type: integer - name: record_id in: path description: ID of the record required: true schema: type: integer - name: page in: query description: page number (default 1) required: false schema: type: integer - name: per_page in: query description: number of children (records uri) per page (default 10) required: false schema: type: integer responses: '200': description: ok content: application/json: schema: type: object properties: meta: type: object properties: api_version: type: string request: type: string response_time: type: string format: date-time http_code: type: integer format: int32 error_type: type: string error_message: type: string response: type: array items: type: string example: /api/v3/records/1/48 '404': description: Story (record) not found default: description: Any (other) error