---
title: "POST /search"
method: POST
path: "/search"
tags: ["search"]
---

# POST /search

`POST /search`

Fulltext search for records or stories.

## About pagination

* offset / limit

    offset starts at 0, the unit is "record"
* page / per_page

    the first page is 1, per_page is the number of "records" per page.

so (page=4 ; per_page=5) <===> (offset=15 ; limit=5)

use (offset/limit) __OR__ (page/per_page)

## About "story_children_limit"

This parameter asks __for each story in the resultset__ to get the __N first__ children (records) of the story.

example with __N=5__ :

* If a story contains __3__ children, the story will expose :
    * children_offset = 0 (always 0 since only first children are returned
    * children_limit = 5 (copy of the story_children_limit parameter)
    * children_count = 3 (number or children returned)
    * children_total = 3 (total number of children in the story)

* If a story contains __7__ children, the story will expose :
    * children_offset = 0 (always 0 since only first children are returned
    * children_limit = 5 (copy of the story_children_limit parameter)
    * children_count = 5 (number or children returned)
    * children_total = 7 (total number of children in the story)

## About "include(s)"

To get smaller / faster response, facets and stories children are ommited by default.

Add __include__ parameters to get those if needed.

each __include__ parameter maps a matching sub-object in the response data.

Since records and stories results are dispatched into 2 separated arrays `response.results.records[]` or
`response.results.stories[]` (depending on the `search_type=0|1` parameter), one must use the correct __include(s)__
that match the result structure.

### facets
```
{
  "response": {
    "facets": [
      {
        "name": "_base",
        "field": "database",
        "values": [
          {
            "value": "Base Beta Version 3.0",
            "raw_value": "Base Beta Version 3.0",
            "count": 2902,
            "query": "database:\"Base Beta Version 3.0\""
          },
          {
            "value": "Base test demo support",
            "raw_value": "Base test demo support",
            "count": 1120,
            "query": "database:\"Base test demo support\""
          },
          ...
        ]
      },
      {
        "name": "Categorie",
        "field": "field.Categorie",
        "values": [
          {
            "value": "USA Août 2018",
            "raw_value": "USA Août 2018",
            "count": 268,
            "query": "field.Categorie=\"USA Août 2018\""
          },
          {
            "value": "Voyage Bahamas",
            "raw_value": "Voyage Bahamas",
            "count": 83,
            "query": "field.Categorie=\"Voyage Bahamas\""
          },
          ...
        ]
      },
      {
        "name": "MotsCles",
        "field": "field.MotsCles",
        "values": [
          {
            "value": "USA",
            "raw_value": "USA",
            "count": 914,
            "query": "field.MotsCles=\"USA\""
          },
          ...
        ]
      },
      ...
    ]
  }
}
```

### suggestions
flatened facets
```
"response": {
  "suggestions": [
    {
      "suggestion": "Demo Online",
      "query": "collection:\"Demo Online\"",
      "hits": 2
    },
    {
      "suggestion": "Voyage Bahamas",
      "query": "field.Categorie=\"Voyage Bahamas\"",
      "hits": 83
    },
    ...
  ]
}
```

### results.records.subdefs ; results.stories.subdefs
```
"response": {
  "results": {
    "records": [
      {
        "subdefs": [
          {
            "name": "document",
            "permalink": {
              "created_on": "2021-09-23T16:04:25+02:00",
              "id": 12539,
              "is_activated": false,
              "label": "TX9329_23",
              "updated_on": "2021-09-23T16:05:34+02:00",
              "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/?token=xxx",
              "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx&download=1",
              "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx"
            },
            "height": 3181,
            "width": 3181,
            "filesize": 30439108,
            "devices": [
              "all"
            ],
            "player_type": "UNKNOWN",
            "mime_type": "image/tiff",
            "substituted": false,
            "created_on": "2021-09-23T16:04:25+02:00",
            "updated_on": "2021-09-23T16:04:25+02:00",
            "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz",
            "url_ttl": 7200
          },
          {
            "name": "preview",
            "permalink": {
              "created_on": "2021-09-23T16:04:46+02:00",
              "id": 12541,
              "is_activated": false,
              "label": "TX9329_23",
              "updated_on": "2021-09-23T16:05:34+02:00",
              "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/?token=xxx",
              "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx&download=1",
              "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx"
            },
            "height": 800,
            "width": 800,
            "filesize": 112906,
            "devices": [
              "screen"
            ],
            "player_type": "IMAGE",
            "mime_type": "image/jpeg",
            "substituted": false,
            "created_on": "2021-09-23T16:04:46+02:00",
            "updated_on": "2021-09-23T16:04:46+02:00",
            "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz",
            "url_ttl": 7200
          },
          ...
        ]
      }
    ]
  }
}
```

### results.records.caption ; results.stories.caption
simple metadata
```
"response": {
  "results": {
    "records": [
      {
        "caption": [
          {
            "meta_structure_id": 12,
            "name": "Titre",
            "value": "New demo pictures - Oceans"
          },
          {
            "meta_structure_id": 4,
            "name": "MotsCles",
            "value": "Bahamas ; mer ; Nassau ; plage ; nuage ; turquoise ; ocean ; sea ; Atlantic"
          },
          ...
        ]
      }
    ]
  }
}
```

### results.records.metadata ; results.stories.metadata
complete metadata with labels
```
{
  "response": {
    "results": {
      "records": [
        {
          "metadata": [
            {
              "meta_structure_id": 12,
              "name": "Titre",
              "labels": {
                "fr": "Titre principal",
                "en": "Headline title",
                "de": "Titre",
                "nl": "Titre"
              },
              "meta_id": 346744,
              "value": "New demo pictures - Oceans"
            },
            {
              "meta_structure_id": 4,
              "name": "MotsCles",
              "labels": {
                "fr": "Mots Clés",
                "en": "Keywords",
                "de": "MotsCles",
                "nl": "MotsCles"
              },
              "meta_id": 346745,
              "value": "Bahamas"
            },
            ...
          ]
        }
      ]
    }
  }
}
```

### results.records.status ; results.stories.status
```
"response": {
  "results": {
    "records": [
      {
        "status": [
          {
            "bit": 8,
            "state": false
          },
          {
            "bit": 9,
            "state": true
          },
          ...
        ]
      }
    ]
  }
}
```

### results.records.thumbnail ; results.stories.thumbnail
always included

### results.records.technical_informations
always included
  
_nb:_ since stories are not related to a document, there is no technical_informations for stories.
    
### results.records.stories
Include a list of stories that contains the record
  
stories is an array of small objects containing only the `story_id` (= `record_id`) of the story.
```
"response": {
  "results": {
    "records": [
      {
        "stories": [
          {
            "story_id": 100
          },
          {
            "story_id": 102
          },
          ...
        ],
        ...
      },
      ...
    ]
  }
}
```
  
### results.stories.children
In story search mode, will publish a children[] array for each result. See _story_children_limit_ parameter.

children is an array of records, with same structure as a result record.
```
"response": {
  "results": {
    "stories": [
      {
        "children": [
          {
            // record structure
          },
          ...
        ],
        ...
      },
      ...
    ]
  }
}
```
### results.records.children.thumbnail
### results.records.children.technical_informations
### results.records.children.subdefs
### results.records.children.caption
### results.records.children.metadata
### results.records.children.status
see result.records.* includes.

## Query parameters

- `query` string
- `search_type` 0 | 1
- `bases` integer[]
- `page` integer
- `per_page` integer
- `offset` integer
- `limit` integer
- `story_children_limit` integer
- `include` string[]

## Response `200`

ok

- ApiResponseSearch — unresolved $ref

## Other responses

- `default` — unresolved $ref

## Changes

- **2021-12-09** (v3) `0bc4420fcd7c` — 15 info
  - added the new optional `query` request parameter `bases`
  - added the enum value `results.records.caption` to the property `items/` of the `query` request parameter `include`
  - added the enum value `results.records.children` to the property `items/` of the `query` request parameter `include`
  - added the enum value `results.records.children.caption` to the property `items/` of the `query` request parameter `include`
  - …11 more
- **2021-08-11** (v3) `9916491b97b4` — 14 breaking, 1 warning
  - removed the enum value `results.records.caption` from the property `items/` of the `query` request parameter `include`
  - removed the enum value `results.records.children` from the property `items/` of the `query` request parameter `include`
  - removed the enum value `results.records.children.caption` from the property `items/` of the `query` request parameter `include`
  - removed the enum value `results.records.children.metadata` from the property `items/` of the `query` request parameter `include`
  - …11 more

[Change history](https://skmtc.dev/alchemy-fr/apis/phraseanet-api/changes/search/post.md)

---

[API](https://skmtc.dev/alchemy-fr/apis/phraseanet-api.md) · [All operations](https://skmtc.dev/alchemy-fr/apis/phraseanet-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/alchemy-fr/phraseanet-api/revisions/ccf1f8e89dfd/schema)