Cloud recording: Start recording

Use this endpoint to start a recording.

To find the recorded file, use a unique value for filename or callback_url in the request body. See the Quickstart for a sample workflow.

Request

Method	URL
`POST`	`https://services.aircore.io/recording`

Headers

Header	Required	Value	Description
`Authorization`	Yes	`Bearer` `SECRET_API_KEY`	Use a secret API key from the Developer Console.
`Content-Type`	Yes	`application/json`

Request body

{
  "storage": {
    "filename": "record",
    "s3": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "bucket": "S3_BUCKET_NAME",
      "region": "us-east-1",
      "server_side_encryption": "AES256"
    }
  },
  "location": {
    "latitude": 40.785091,
    "longitude": -73.968285
  },
  "user_id": "4a1c5943-994e-4c2b-a717-7f6ff42c5396",
  "channel_id": "9a01c703-48db-4101-ad8a-c907f04f0c3a",
  "callback_url": "https://your_server.com/recordings?id=2348723149"
}

Request JSON elements

Element			Type	Required	Description
`storage`			Object	Yes	Object for third-party storage details.
┗	`filename`		String	Yes	Prefix for the filename of the recording.
┗	`s3`		Object	Yes	Object for Amazon S3 details.
	┗	`access_key_id`	String	Yes	S3 access key ID.
	┗	`secret_access_key`	String	Yes	S3 secret access key.
	┗	`bucket`	String	Yes	S3 bucket name.
	┗	`region`	String	Yes	Region for the S3 bucket. For possible values, see the codes at AWS service endpoints.
	┗	`server_side_encryption`	String	No	Encryption format for S3. Possible values: `AES256` (default) `aws:kms` (AWS Key Management Service)
`location`			Object	Yes	Location for selecting the recording server. To minimize latency, use the most accurate location you can, such as: The client device that started the recording Your closest server The general region of your clients
┗	`latitude`		Number	Yes	Latitude in decimal degrees. Possible values: `-90` to `90`.
┗	`longitude`		Number	Yes	Longitude in decimal degrees. Possible values: `-180` to `180`.
`user_id`			String	Yes	ID for the user who initiated recording.
`channel_id`			String	Yes	ID for the channel to record.
`callback_url`			String	No	Unique callback URL for updates on the recording. For more info, see Callbacks.

Response

Response body

{
  "url": "https://services.aircore.io:443/recording/http%3A%2F%2Fvandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com%3A8080%2Frecording%2F1677608374942-0-503309",
  "state": "started",
  "startTime": 1665460533516,
  "elapsedTime": 0
}

Response JSON elements

Element	Type	Description
`url`	String	URL that you can use to stop recording. Format: `https://services.aircore.io:443/recording/`UNIQUE_IDENTIFIER`.
`state`	String	State of the recording. The value is always `started` for this endpoint.
`startTime`	Number	Start time. Unix epoch time in milliseconds.
`elapsedTime`	Number	Elapsed time since the recording started in milliseconds. The value is always `0` for this endpoint.

HTTP status codes

Code	Description
`201`	Started recording.
`400`	Missing or invalid parameter in the start recording request.
`401`	Invalid token.
`5XX`	Recording failed to start due to an internal server error.