Overview

The ContentGroove Developer API enables you to add the power of ContentGroove’s video AI to your own applications and workflows.

Webhooks are a way for ContentGroove to send video information to your application, to update your system and/or trigger other business processes.

You can use Webhooks and the Developer API separately or together.

Getting Started with Webhooks

• Sign up for an account at app.contentgroove.com
• Read “Using Webhooks” on the API Reference page
• Visit the Webhooks page and create a new webhook

Using Webhooks

Webhooks, also known as callbacks, are a way for ContentGroove to notify your application as soon as possible after an event has occurred in ContentGroove. For example after a media completes processing, ContentGroove can use a webhook to notify your application with information about the video: Suggested clips, transcription, and so on. You can use the information sent to update your system and/or use the webhook to trigger other business processes.

The webhook request is sent as an HTTP POST containing a payload of JSON-formatted data. For the details of the payload format see the “CALLBACKS” sections below.

When your application receives the webhook request, it must respond with a 200 HTTP status code (success). If a 200 HTTP status code is not returned, ContentGroove will assume that the webhook was not delivered and will retry a limited number of times, using an exponential backoff algorithm.

ContentGroove makes a best effort to attempt to send the webhook at least once. Applications receiving webhooks must tolerate the possibility of a single webhook payload being sent more than once (idempotent behavior). Applications receiving webhooks should tolerate the possibility that a webhook could not be delivered (for example your application was down when delivery was attempted).

Getting Started with the Developer API

• Sign up for an account at app.contentgroove.com
• Visit the API Keys page
  • Create a new API Key then copy and save the value.

    ⚠️ IMPORTANT: This API Key is intended only for use on the server side. Be sure never to use a server-side API Key in client-side (web, mobile, or otherwise) code. ⚠️

• View all available endpoints, and try the API, on our API Reference page

Using the Developer API

• Create a new media (video or audio) in ContentGroove
  • If the video or audio is available from a URL, you can create a media by providing the source_url parameter. ContentGroove will fetch the video or audio from the URL if possible.
  • Or, you can create a media from a video or audio file which you upload directly to ContentGroove (see File Uploading section below).
• After the new media is created, at first it will be in a “processing” state. Depending on the size and duration of the video or audio file, it will take some time for processing to complete.
  • You can use ContentGroove Webhooks to be notified immediately when processing has completed. (Details coming soon.)
  • You can also use the API to read the state of the media, to determine if the media has completed processing yet.
• After the media has completed processing, you can access all of these details about the media:
  • The media name and description
  • The transcription of spoken words
  • Topics and keywords which were discussed in the transcription
  • Suggested video clips are automatically created
• In addition to the automatically created video clips, you can create more video clips from the media

Response Codes

The following is a comprehensive list of the status codes you may receive while using the ContentGroove API:

• 200 “Ok”
  • The request was valid
• 400 “Bad Request
  • This is returned when there was a problem parsing the JSON body of your request if you supplied the ‘Content-Type’: ‘application/json’ header, or if your request is missing the ‘Content-Type’ header altogether
• 401 “Unauthorized”
  • This is returned when you are attempting to perform an action on a resource that you are not authorized to do
• 402 “Payment Required”
  • This is returned when you are attempting to perform an action that would push your account above a usage limit. You can view your usage at: https://app.contentgroove.com/quota_usage
• 404 “Not Found”
  • This is returned when the resource you are trying to view does not exist
• 429 “Too Many Requests”
  • This is returned when you have performed too many requests within a given period of time
• 500 “Internal Server Error”
  • This is returned when your request was valid but there was a problem on our end

File Uploading

• Step 1: Make a GET request to the direct uploads URL endpoint (/api/v1/direct_uploads) to receive an upload URL to upload the file to and an upload id.
• Step 2: Make a PUT request with the file as the body to the upload URL received in step 1. The response will have a 200 status with no body if the upload is successful.

  curl -T /path/to/file upload_url
  

• Step 3: After uploading the file to the upload URL, make a POST request to the create medias endpoint (/api/v1/medias), with the upload id and optionally a name and description for the new media.

  At this time, file uploads are limited to 5gb per file.

Allowed media types

Video:

• Supported: Most common video formats and codecs are supported.
• Recommended: mp4

Audio:

• Supported: aac, mp3, flac, ogg, wav, and wma
• Recommended: aac

Authentication

You can use the API Key to authenticate your API requests using any of these methods. (Replace abc123 with your actual API Key.)

• Request header Authorization: Bearer abc123
• Request header X-API-KEY: abc123
• Query parameter api_key=abc123

  ⚠️ IMPORTANT: This API Key is intended only for use on the server side. Be sure never to use a server-side API Key in client-side (web, mobile, or otherwise) code. ⚠️

Link to openapi.json spec

• https://api.contentgroove.com/api-docs/v1/openapi.json

Use this page to mock ContentGroove API in your testing and development.

Run our mock API sample using the open source WireMock library, or in the free edition of WireMock Cloud. You'll have a working API server simulating the behavior of ContentGroove API, which will allow you to keep building and testing even if the actual API you isn't currently available.