Skip to main content

File metadata

Need to see how it's going with the recorded media files? Or do you just need an overview of your real estate? We got you covered!

What you'll need​

  • Your secret API key
  • file UUID - you get this reference after you create a token for the annotation tool or the recorder
  • category_id - optional, but if you have it, it will be easier to find the file you're looking for
  • entity_id - optional, but if you have it, it will be easier to find the file you're looking for
  • external_user_id - optional, but if you have it, it will be easier to find the file you're looking for

Retrieving the status og a single file​

You need to send us a request and we'll tell you how it's going

tip

This is brilliant when you have a user waiting to play a video that is still converting. You can use this endpoint to check if the file is ready to play before you show it to the user.

curl --location \
     --header 'Authorization: Bearer <API key>' \
     --request GET 'https://api.pathfindr.dev/api/files/<UUID>/status'

Here is what you get:

{
    "uuid":"<UUID>", 
    "status":"converting" 
    /* ... or  allocated, created, queued, converted, converting_failed */
}

For media files here are the possible statuses and explanations

  • allocated: you created an access token for either the recorder or the annotation tool and we gave you a media_file_id but the user hasn't recorded anything yet or abandoned the process
  • created: the user finished recording and a media file was uploaded to our service
  • queued: the media file is waiting in line to be converted
  • converting: the media file is being processed to support multiple browsers, devices and adaptive streaming
  • converted: all conversions are ready
  • conversion_failed: something went wrong during the conversion process, but you can be sure we are on it

For documents there are only two possible statuses:

  • allocated - you created an access token for the annotation tool and we gave you a document_file_id but the user hasn't uploaded anything yet or abandoned the process
  • created - the user finished annotating and a document file was uploaded to our service
tip

No matter how the conversion process goes, the original media file is always accessible. You can find more info about it here

Get the status of multiple files​

This endpoint is useful when you need to check the status of multiple files at the same time. You can either send an array of UUID's or a combination of entity_id, category_id and external_user_id.

tip

This endpoint is normally used to get your database back in sync with our service. You can use it to check if the files you have in your database is still available in our service.

Get the status of files by UUID's​

Send a POST request to the Pathfindr API with the UUIDs of the files you want to get the status of. Replace the * API key * and UUIDs in the request with your API key and UUIDs.

curl --location 'https://api.pathfindr.dev/api/files/metadata' \
--header 'Authorization: Bearer API-KEY' \
--form 'file_uuids[]="881dbef6-6daf-44da-b59d-27dc390e5541"' \
--form 'file_uuids[1]="510c4dd8-0640-40da-abd9-c4f07cd71c3d"'

The response will contain metadata about the files requested like in the example below.

[
    {
        "uuid": "881dbef6-6daf-44da-b59d-27dc390e5541",
        "external_user_id": "Jeppe",
        "category_id": "Group 1",
        "entity_id": "Acme school",
        "created_at": "2024-01-25T11:02:24.000000Z",
        "state": "converted"
    },
    {
        "uuid": "510c4dd8-0640-40da-abd9-c4f07cd71c3d",
        "external_user_id": "Laszlo",
        "category_id": "Group 2",
        "entity_id": "Hello School",
        "created_at": "2024-01-25T11:02:30.000000Z",
        "state": "converted"
    }
]

Getting metadata on files by entity_id, category_id and external_user_id.​

Send a POST request to the Pathfindr API with the entity_id, category_id and external_user_id of the files you want to get metadata on. The query will return all files that match the criteria.

tip

For example if you send a request with category_id="group1" and entity="entity_1" and no external_user_id=null the query will return all files that have the category_id="group1" and entity="entity_1" no matter what external_user_id they have.

info

To get files by metadata you need to have set the metadata when you uploaded the files. See annotation tool or recorder for more information.

Replace the * API key * in the request with your API key.

curl --location 'https://api.pathfindr.dev/api/files/metadata   ' \
--header 'Authorization: Bearer API-KEY' \
--form 'external_user_id="1"' \
--form 'entity_id="1"' \
--form 'category_id="1"' \
--form 'file_uuids[]=""'