Metadata

Learn how to work with metadata using the Alphamoon REST API

Filter collections by the value

Using the Alphamoon API you can filter collections by set metadata values.

For example, if you want to filter only these collections that have already been printed, use the Get collections endpoint:

GET /api/v0.3/processes/{process_id}/collections

In the metadata section include the relevant query. In our case it will be:

{"printed": "yes"}

200: OK Successful Response

{
  "collections": [
    {
      "id": "191719e01ae84f02993168ef95be3c49",
      "name": "Invoice example.pdf",
      "files": [
        {
          "id": "0164f04d3a1e4138b73bb84695395871",
          "collectionId": "191719e01ae84f02993168ef95be3c49",
          "name": "Invoice example.pdf",
          "status": "Accepted",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2024-04-15T15:03:38Z",
          "updatedAt": "2024-04-16T12:29:07Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Accepted",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-04-15T15:03:38Z",
      "updatedAt": "2024-04-29T12:56:52Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 1
  }
}

422: Validation error

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

See the example:

API call

curl -X 'GET' \
  'https://workspace.alphamoon.ai/api/v0.3/processes/93580f176efb48cda64f25cba74d8ca4/collections?offset=0&limit=100&order=created_date%3Adesc&status=Accepted&metadata=%7B%22printed%22%3A%20%22yes%22%7D' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED'

Server response

{
  "collections": [
    {
      "id": "191719e01ae84f02993168ef95be3c49",
      "name": "Invoice example.pdf",
      "files": [
        {
          "id": "0164f04d3a1e4138b73bb84695395871",
          "collectionId": "191719e01ae84f02993168ef95be3c49",
          "name": "Invoice example.pdf",
          "status": "Accepted",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2024-04-15T15:03:38Z",
          "updatedAt": "2024-04-16T12:29:07Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Accepted",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-04-15T15:03:38Z",
      "updatedAt": "2024-04-29T12:56:52Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 1
  }
}

Filter collections by key

Alphamoon API enables you to also filter collection based on the previously defined keys ("true" or "false" option). Let's say you want to see only collections that have a created "printed" key. To do that, use the Get collections endpoint:

GET /api/v0.3/processes/{process_id}/collections

In the metadata section include the relevant query. In our case it will be:

{"printed": {"$exists": true}}

In the response you will get all collections for which the "printed" key was defined:

200: OK Successful response

{
  "collections": [
    {
      "id": "191719e01ae84f02993168ef95be3c49",
      "name": "Invoice example.pdf",
      "files": [
        {
          "id": "0164f04d3a1e4138b73bb84695395871",
          "collectionId": "191719e01ae84f02993168ef95be3c49",
          "name": "Invoice example.pdf",
          "status": "Accepted",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2024-04-15T15:03:38Z",
          "updatedAt": "2024-04-16T12:29:07Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Accepted",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-04-15T15:03:38Z",
      "updatedAt": "2024-04-29T12:56:52Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    },
    {
      "id": "86fc8d905d0e4cefb042e6cd707fb51f",
      "name": "Invoices 2024.pdf",
      "files": [
        {
          "id": "929b1189d66b4874842d66bd274d435f",
          "collectionId": "86fc8d905d0e4cefb042e6cd707fb51f",
          "name": "Invoices 2024.pdf",
          "status": "Rejected",
          "progress": 100,
          "numberOfPages": 3,
          "createdAt": "2024-01-05T10:17:08Z",
          "updatedAt": "2024-04-16T13:55:49Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Rejected",
      "progress": 100,
      "numberOfPages": 3,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-01-05T10:17:08Z",
      "updatedAt": "2024-04-29T14:49:56Z",
      "metadata": {
        "printed": "no"
      },
      "availableForTraining": true,
      "duplicates": []
    },
    {
      "id": "8284a1a1b68246868924d50feee1ee38",
      "name": "Skynova_Invoice_Example.jpg",
      "files": [
        {
          "id": "375cc38c4fad4817a00097c629150951",
          "collectionId": "8284a1a1b68246868924d50feee1ee38",
          "name": "Skynova_Invoice_Example.jpg",
          "status": "Needs Review",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2023-12-20T14:57:14Z",
          "updatedAt": "2024-04-18T13:45:03Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Needs Review",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2023-12-20T14:57:14Z",
      "updatedAt": "2024-04-29T14:50:22Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 3
  }
}

422: Validation error

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

See the example:

API call

curl -X 'GET' \
  'https://workspace.alphamoon.ai/api/v0.3/processes/93580f176efb48cda64f25cba74d8ca4/collections?offset=0&limit=100&order=created_date%3Adesc&metadata=%7B%22printed%22%3A%20%7B%22%24exists%22%3A%20true%7D%7D' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED'

Server response

{
  "collections": [
    {
      "id": "191719e01ae84f02993168ef95be3c49",
      "name": "Invoice example.pdf",
      "files": [
        {
          "id": "0164f04d3a1e4138b73bb84695395871",
          "collectionId": "191719e01ae84f02993168ef95be3c49",
          "name": "Invoice example.pdf",
          "status": "Accepted",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2024-04-15T15:03:38Z",
          "updatedAt": "2024-04-16T12:29:07Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Accepted",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-04-15T15:03:38Z",
      "updatedAt": "2024-04-29T12:56:52Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    },
    {
      "id": "86fc8d905d0e4cefb042e6cd707fb51f",
      "name": "Invoices 2024.pdf",
      "files": [
        {
          "id": "929b1189d66b4874842d66bd274d435f",
          "collectionId": "86fc8d905d0e4cefb042e6cd707fb51f",
          "name": "Invoices 2024.pdf",
          "status": "Rejected",
          "progress": 100,
          "numberOfPages": 3,
          "createdAt": "2024-01-05T10:17:08Z",
          "updatedAt": "2024-04-16T13:55:49Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Rejected",
      "progress": 100,
      "numberOfPages": 3,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2024-01-05T10:17:08Z",
      "updatedAt": "2024-04-29T14:49:56Z",
      "metadata": {
        "printed": "no"
      },
      "availableForTraining": true,
      "duplicates": []
    },
    {
      "id": "8284a1a1b68246868924d50feee1ee38",
      "name": "Skynova_Invoice_Example.jpg",
      "files": [
        {
          "id": "375cc38c4fad4817a00097c629150951",
          "collectionId": "8284a1a1b68246868924d50feee1ee38",
          "name": "Skynova_Invoice_Example.jpg",
          "status": "Needs Review",
          "progress": 100,
          "numberOfPages": 1,
          "createdAt": "2023-12-20T14:57:14Z",
          "updatedAt": "2024-04-18T13:45:03Z",
          "metadata": {}
        }
      ],
      "priority": false,
      "split": false,
      "status": "Needs Review",
      "progress": 100,
      "numberOfPages": 1,
      "processId": "93580f176efb48cda64f25cba74d8ca4",
      "createdAt": "2023-12-20T14:57:14Z",
      "updatedAt": "2024-04-29T14:50:22Z",
      "metadata": {
        "printed": "yes"
      },
      "availableForTraining": true,
      "duplicates": []
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 3
  }
}

See next: