Content

The Content API lets you manage and manipulate video content through a comprehensive set of endpoints. Built for external applications and content management systems, it provides full CRUD operations to create, read, update, and delete video content. Whether you’re building a content management system, integrating with third-party platforms, or automating content workflows, this API gives you complete control over your video library.

Use this API when you need:

Programmatic content management and updates
Bulk content operations and batch processing
Integration with external systems and platforms
Automated content workflows and synchronization

Authentication Type

Use the read-write-update endpoint authentication.

Creating Content

The content creation process involves two main steps:

Create Content Metadata
First, create the content object by sending a POST request with the content metadata:
```
POST https://external.parone.io/v2/content/
```
Include the following required headers:
- Authorization: Your API authentication token
- Content-Type: application/json
The request body should contain the content metadata in JSON format. See the Creation JSON Fields section below for details.
Upload Media Files
After creating the content metadata, you’ll need to upload the associated media files (video and/or thumbnail). Once the upload is complete, notify the system by sending a POST request to:
```
POST https://external.parone.io/v2/content/complete
```
This endpoint will process the uploaded files and make the content available in your library.

Creation JSON fields

Field	Type	Description
`thumbnailUrl`	string (optional)	The URL to use as the thumbnail for the content. If this is null the system will make a thumbnail and its URL will be returned to you
`contentSize`	number	The length, in bytes, of your content
`contentKey`	string (optional)	8 characters or less, letters and numbers. If you don’t pass a contentKey or it’s null a contentKey will be created for you and returned in the result object
`title`	string (optional)	If no title is passed in the video will have an empty title. Note that this is supported but not normal
`description`	string (optional)	If no description is passed in the video will have an empty description
`categories`	array of strings (optional)	A list of strings. If no categories are specified none will be set on the content. Note that these are case-sensitive. If a category is specified but doesn’t exist in the organization it will be created
`tags`	array of strings (optional)	A list of strings. If no tags are specified none will be set on the content. Note that these are case-sensitive. If a tag is specified but doesn’t exist in the organization it will be created
`events`	array of strings (optional)	A list of strings. If no events are specified none will be set on the content. Note that these are case-sensitive. If an event is specified but doesn’t exist in the organization it will be created
`customFields`	array of objects (optional)	An array of key-value pairs. Example: `[{"my_key": 22}, {"fruit": "orange"}, {"author": "frank"}]`. The customFields, if specified, will be associated with the content
`suffix`	string (optional)	The file suffix of the incoming video, including the period. Can only be .mp4 or .mov. Defaults to .mp4 if not specified

Examples

# with a contentKey
{
  "contentKey" : "1234abcd",
  "contentSize" : 1234567,
  "description" : "One of the most amazing videos made by mankind.",
  "title" : "My excellent golf video",
  "thumbnailUrl" : "https://www.google.com/image.jpg",
  "categories" : ["golf", "awesomeness", "putting", "primary"],
  "tags" : ["bombast", "firstPage"],
  "events" : ["PGA Championship 2025"],
  "customFields" : [{"author": "manny"}, {"dateExported": "2025-05-20"}, {"director":"bob"}]
}

# no contentKey
{
  "contentSize" : 1234567,
  "description" : "One of the most amazing videos made by mankind.",
  "title" : "My excellent golf video",
  "thumbnailUrl" : "https://www.google.com/image.jpg",
  "categories" : ["golf", "awesomeness", "putting", "primary"],
  "tags" : ["bombast", "firstPage"],
  "events" : ["Masters 2025"],
  "customFields" : [{"author": "manny"}, {"dateExported": "2025-05-20"}, {"director":"bob"}]
}

# Just the basics
{
  "description" : "One of the most amazing videos made by mankind.",
  "title" : "My excellent golf video",
  "contentSize" : 1234567
}

Returned Object

If successful, you’ll receive an object containing the content metadata, upload URLs, and configuration details. The response includes a thumbnailUploadUrl for the thumbnail and contentUploadData for the video file upload.

Example Response with contentKey

{
  "contentKey": "1234abcd",
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "thumbnailUrl": "https://www.google.com/image.jpg",
  "categories": ["golf", "awesomeness", "putting", "primary"],
  "tags": ["bombast", "firstPage"],
  "events": [],
  "customFields": [
    {"author": "manny"},
    {"dateExported": "2025-05-20"},
    {"director": "bob"}
  ],
  "contentSize": 1234567,
  "thumbnailUploadUrl": "LONG_URL",
  "contentUploadData": {
    "chunkSize": 100000000,
    "uploadId": "SOME_VALUE",
    "key": "1234abcd/1234abcd.mp4",
    "signedUrls": ["LIST_OF_SIGNED_URLs"]
  }
}

Example Response without contentKey

{
  "contentKey": "asdf1234",
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "thumbnailUrl": "https://www.google.com/image.jpg",
  "categories": ["golf", "awesomeness", "putting", "primary"],
  "tags": ["bombast", "firstPage"],
  "events": ["putting competition 2025"],
  "customFields": [
    {"author": "manny"},
    {"dateExported": "2025-05-20"},
    {"director": "bob"}
  ],
  "contentSize": 1234567,
  "thumbnailUploadUrl": "LONG_URL",
  "contentUploadData": {
    "chunkSize": 100000000,
    "uploadId": "SOME_VALUE",
    "key": "asdf1234/asdf1234.mp4",
    "signedUrls": ["LIST_OF_SIGNED_URLs"]
  }
}

Example Response with Minimal Fields

{
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "contentKey": "asdf1234",
  "thumbnailUrl": "https://thumbnails.parone.io/asdf1234.jpg",
  "categories": [],
  "tags": [],
  "events": [],
  "customFields": [],
  "contentSize": 1234567,
  "thumbnailUploadUrl": "LONG_URL",
  "contentUploadData": {
    "chunkSize": 100000000,
    "uploadId": "SOME_VALUE",
    "key": "asdf1234/asdf1234.mp4",
    "signedUrls": ["LIST_OF_SIGNED_URLs"]
  }
}

You should upload the thumbnail first, then the parts of the video file. You will need the ETag for each uploaded part.

Error Handling

If there was an error, you’ll receive a non-200 status code and an error message object:

{ "message": "the error message" }

Common Error Codes

Status Code	Description
401	Authentication failed - API headers are incorrect
400	Bad Request - content key is already in use
400	Bad Request - invalid JSON in POST body

Upload Requirements

Video File

Format: MP4
Resolution: 1080p
Codec: H.264
Audio: AAC

Thumbnail Image

Format: JPG
Resolution: 1920x1080
Aspect Ratio: 16:9
Maximum Size: 5MB

Upload Completion

After successfully uploading all video parts and the thumbnail, you need to notify the system by calling the complete endpoint:

POST https://external.parone.io/v2/content/complete

Request Body

{
  "uploadId": "SOME_VALUE",
  "key": "THE_PROVIDED_KEY_IN_contentUploadData",
  "parts": [
    {
      "PartNumber": 1,
      "ETag": "etag_for_part_1"
    },
    {
      "PartNumber": 2,
      "ETag": "etag_for_part_2"
    }
  ]
}

Field	Type	Description
`uploadId`	string	The upload ID provided in the creation response
`key`	string	The key provided in contentUploadData
`parts`	array	Array of objects containing PartNumber and ETag for each uploaded part

Retrieving Content

To retrieve information about a specific piece of content, make a GET request using its contentKey.

GET https://external.parone.io/v2/content?contentKey=CONTENT_KEY

Field	Type	Description
`contentKey`	string	The unique identifier of the content to retrieve

Returned Object

The API will return the updated content object with all fields:

{
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "contentKey": "asdf1234",
  "thumbnailUrl": "https://thumbnails.parone.io/asdf1234.jpg",
  "categories": [],
  "tags": [],
  "events": [],
  "customFields": []
}

Error Response

If there was an error, you’ll receive a non-200 status code and an error message:

{ "message" : "the error message"}

Common Error Codes

Status Code	Description
401	Authentication failed - API headers are incorrect
404	Not Found - content key does not exist

Updating Content

The content update process involves three main steps:

Retrieve Content Metadata

First, get the content object by sending a GET request with the contentKey:

GET https://external.parone.io/v2/content?contentKey=CONTENT_KEY

{
  "contentKey": "1234abcd",
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "thumbnailUrl": "https://www.google.com/image.jpg",
  "categories": ["golf", "awesomeness", "putting", "primary"],
  "tags": ["bombast", "firstPage"],
  "events": ["Show episode 1"],
  "customFields": [
    {"author": "manny"},
    {"dateExported": "2025-05-20"},
    {"director": "bob"}
  ]
}

Modify Content

Update the values in the returned object with your desired changes.

{
  "contentKey": "1234abcd",
  "description": "One of the most amazing videos made by anyone.",
  "title": "The most excellent golf video",
  "thumbnailUrl": "https://www.google.com/image.jpg",
  "categories": ["golf", "awesomeness", "putting", "primary"],
  "tags": ["bombast", "firstPage"],
  "events": ["Show episode 2"],
  "customFields": [
    {"author": "JR"},
    {"dateExported": "2025-05-20"},
    {"director": "Taz"}
  ]
}

PUT Update
Send a PUT request with the modified content.
```
PUT https://external.parone.io/v2/content
```

Creation JSON fields

Field	Type	Description
`thumbnailUrl`	string (required)	The URL to use as the thumbnail for the content. If this is null the system will make a thumbnail and its URL will be returned to you
`contentKey`	string (required)	8 characters or less, letters and numbers. If you don’t pass a contentKey or it’s null a contentKey will be created for you and returned in the result object
`title`	string (required)	If no title is passed in the video will have an empty title. Note that this is supported but not normal
`description`	string (required)	If no description is passed in the video will have an empty description
`categories`	array of strings (required)	A list of strings. If no categories are specified none will be set on the content. Note that these are case-sensitive. If a category is specified but doesn’t exist in the organization it will be created
`tags`	array of strings (required)	A list of strings. If no tags are specified none will be set on the content. Note that these are case-sensitive. If a tag is specified but doesn’t exist in the organization it will be created
`events`	array of strings (required)	A list of strings. If no events are specified none will be set on the content. Note that these are case-sensitive. If an event is specified but doesn’t exist in the organization it will be created
`customFields`	array of objects (required)	An array of key-value pairs. Example: `[{"my_key": 22}, {"fruit": "orange"}, {"author": "frank"}]`. The customFields, if specified, will be associated with the content

Returned Object

If successful, you’ll receive an object containing the content metadata.

{
  "contentKey" : "1234abcd",
  "description" : "One of the most amazing videos made by anyone.",
  "title" : "The most excellent golf video",
  "thumbnailUrl" : "https://www.google.com/image.jpg",
  "categories" : ["golf", "awesomeness", "putting", "primary"],
  "tags" : ["bombast", "firstPage"],
  "events" : ["Show episode 2"],
  "customFields" : [{"author": "JR"}, {"dateExported": "2025-05-20"}, {"director":"Taz"}]
}

Error Handling

If there was an error, you’ll receive a non-200 status code and an error message object:

{ "message" : "the error message"}

Common Error Codes

Status Code	Description
401	Authentication failed - API headers are incorrect
404	Not Found - content key does not exist
400	Bad Request - invalid data in request

Deleting Content

To delete a specific piece of content, make a DELETE request using its contentKey.

DELETE https://external.parone.io/v2/content?contentKey=CONTENT_KEY

Field	Type	Description
`contentKey`	string	The unique identifier of the content to retrieve

Returned Object

The API will return the deleted content object with all fields:

{
  "description": "One of the most amazing videos made by mankind.",
  "title": "My excellent golf video",
  "contentKey": "asdf1234",
  "thumbnailUrl": "https://thumbnails.parone.io/asdf1234.jpg",
  "categories": [],
  "tags": [],
  "events": [],
  "customFields": []
}

Error Response

If there was an error, you’ll receive a non-200 status code and an error message:

{ "message" : "the error message"}

Common Error Codes

Status Code	Description
401	Authentication failed - API headers are incorrect
404	Not Found - content key does not exist

Content

Authentication Type

Creating Content

Create Content Metadata

Upload Media Files

Creation JSON fields

Examples

Returned Object

Example Response with contentKey

Example Response without contentKey

Example Response with Minimal Fields

Error Handling

Common Error Codes

Upload Requirements

Video File

Thumbnail Image

Upload Completion

Request Body

Retrieving Content

Returned Object

Error Response

Common Error Codes

Updating Content

Retrieve Content Metadata

Modify Content

PUT Update

Creation JSON fields

Returned Object

Error Handling

Common Error Codes

Deleting Content

Returned Object

Error Response

Common Error Codes