Create new fragment

POST

/fragments

curl --request POST \
  --url https://legion.picogrid.com/v2/fragments \
  --header 'Content-Type: application/json' \
  --data '{ "terminal_id": "example", "stream_id": "example", "timestamp": 1, "location": { "type": "lat_lng_alt", "altitude": 1, "latitude": 1, "longitude": 1 }, "meta_data": { "additionalProperty": "example" }, "payload": { "primitive_fragment_type": "blob", "file_id": "example" } }'

• The server that hosts the Legion prod API

Create a new fragment by specifying the properties of the new object in the request body

Request Body^required

Specify the fields of the fragment here

Media typeapplication/json

object

terminal_id

required

string

stream_id

required

string

timestamp

required

The time the fragment was recorded. The timestamp is an epoch milliseconds integer. See https://en.wikipedia.org/wiki/Unix_time for more information

integer

location

required

One of:

Latitude, Longitude, Altitude

Latitude, Longitude, Altitude

Provide the latitude and longitude of the resource using WGS84, and the altitude of the resource in meters above sea level

object

type

required

string

Allowed values: lat_lng_alt

altitude

required

The altitude of the resource in meters above sea level

number

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

meta_data

Any additional metadata that that may be relevant for this type of fragment. See meta_data documentation for more information

object

key

additional properties

payload

required

One of:

Blob Fragment

Blob Fragment

object

primitive_fragment_type

required

This ‘blob’ type is for uploading arbitrary types of data to Legion that is stored in our blob storage and can be as large as needed. It must have the same primitive fragment type as the stream’s fragment type however.

string

Allowed values: blob

file_id

required

To upload an arbitrarily sized fragment of any type to Legion we need you to first get an upload url from Legion, and then follow the instructions for that endpoint to upload the file. The response will contain a file_id which you need to specify here. You cannot create a blob fragment before the file has been uploaded to our blob storage.

string

JSON Fragment

JSON Fragment

object

primitive_fragment_type

required

This ‘json’ type is for uploading smaller json objects with a max size of 200kb. Remember that this primitive fragment type must also match the primitive fragment type of the stream’s fragment type you are uploading to

string

Allowed values: json

json_data

required

JSON Data

Any json object that represents your fragment is under 200kb in size

object

key

additional properties

Responses

200

Success

Media typeapplication/json

One of:

Blob Fragment

Blob Fragment

object

id

required

string

primitive_fragment_type

required

This key can be used as a discriminator for which type of fragment you have received. In this case the value is ‘blob’. The fragment is stored in our blob storage, which we use for large files and unstructured data, so we provide the fragment to you via the presigned url found in this object.

string

Allowed values: blob

presigned_url

required

An http url you can send a GET request to in order to fetch the blob data of the fragment. If it is an image for example you can use this url directly in an <img> tag to display the image. The url is only valid for 24 hours, so will need to be refetched after that time if needed. The url should be treated as a secret token, and only shared with people you want to have access to the data.

string

fragment_type_id

required

string

timestamp

required

The time the fragment was recorded. The timestamp is an epoch milliseconds integer. See https://en.wikipedia.org/wiki/Unix_time for more information

integer

processed_timestamp

required

The time the fragment was received and created by Legion. The timestamp is an epoch milliseconds integer. See https://en.wikipedia.org/wiki/Unix_time for more information

integer

location

required

Location

Gives multiple different formats and units to choose between that all represent the location of the resource

object

lat_long_alt

required

Latitude, Longitude, Altitude

Provides the latitude and longitude of the resource using WGS84, and the altitude of the resource in meters above sea level

object

altitude

required

The altitude of the resource in meters above sea level

number

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

meta_data

required

Any additional metadata that that may be relevant for this type of fragment. See meta_data documentation for more information

object

key

additional properties

stream_id

required

string

terminal_id

required

string

JSON Fragment

JSON Fragment

object

id

required

string

primitive_fragment_type

required

This key can be used as a discriminator for which type of fragment you have received. In this case the value is ‘json’. The fragment is stored as a json object smaller than 200kb and is therefore provided directly in the json_data key in this object.

string

Allowed values: json

json_data

required

The json data which describes the fragment

object

key

additional properties

fragment_type_id

required

string

timestamp

required

The time the fragment was recorded. The timestamp is an epoch milliseconds integer. See https://en.wikipedia.org/wiki/Unix_time for more information

integer

processed_timestamp

required

The time the fragment was received and created by Legion. The timestamp is an epoch milliseconds integer. See https://en.wikipedia.org/wiki/Unix_time for more information

integer

location

required

Location

Gives multiple different formats and units to choose between that all represent the location of the resource

object

lat_long_alt

required

Latitude, Longitude, Altitude

Provides the latitude and longitude of the resource using WGS84, and the altitude of the resource in meters above sea level

object

altitude

required

The altitude of the resource in meters above sea level

number

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

meta_data

required

Any additional metadata that that may be relevant for this type of fragment. See meta_data documentation for more information

object

key

additional properties

stream_id

required

string

terminal_id

required

string

Example

{
  "primitive_fragment_type": "blob"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

400

Bad Request Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

401

Authentication Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

403

Unauthorized Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

404

Resource Not Found Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

408

Timeout Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

500

Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link

502

Bad Gateway Error

Media typeapplication/json

object

message

required

string

Example^generated

{
  "message": "example"
}

Headers

Access-Control-Allow-Origin

string

default: *

Example

https://developer.mozilla.org

The Access-Control-Allow-Origin response header indicates whether the response can be shared with requesting code from the given origin. - MDN Link

Access-Control-Allow-Credentials

boolean

default: true

The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is include. - MDN Link