NAV Navbar
shell

Introduction

Welcome to the Voicepods API! The Voicepods API is a premium feature that programatically allows users to access and create resources on Voicepods.

Please note that this early preview of our API. In coming months we will be updating our API to provide more robust information. For specific requests please email at team@voicepods.com.

Authentication

To authorize each request make sure that the base URL is https://app.voicepods.com. You must attached your API key in the Token header as shown below.

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Token token=YOURAPIKEY"

Make sure to replace YOURAPIKEY with your API key.

Voicepods uses API keys to allow access to the API. You can register a new Voicepods API key at our developer portal.

Voicepods expects for the API key to be included in all API requests to the server in a header that looks like the following:

Token token=YOURAPIKEY

Rate Limits

We currently enforce a rate limit of 10 requests every second to our API. If you go above this limit, please email team@voicepods.com.

Introduction

There are 2 resources that you can access using our API. Projects and Pods. In the Project scope, you can access a list of your current Projects, create a new Project, and see all recent pods within all of your projects. The Pod resource represents each audio file that is inside of a Project. You can perform actions such as listing all of the pods inside a project, retrieve one pod, or create a new pod.

Project

{
  name: <string>,
  description: <string>,
  public: <boolean>,
  collaboration: <boolean>
}

Get All Projects

curl "https://app.voicepods.com/api/v1/projects"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

[
  {
      "id": 1,
      "name": "Voicepods",
      "description": "Thoughts by Voicepods",
  },
  {
      "id": 2,
      "name": "Dose of Health",
      "description": "Health-focused podcast from around the internets.",
  },
]

This endpoint retrieves all projects.

HTTP Request

GET https://app.voicepods.com/api/v1/projects

Get a Specific Project

curl "https://app.voicepods.com/api/v1/projects/<id>"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Voicepods",
  "description": "Thoughts by Voicepods",
}

Returns a Project Resource.

URL Parameters

Parameter Description
ID The ID of the project to fetch

HTTP Request

GET https://app.voicepods.com/api/v1/projects/<ID>

Create a new Project

curl "https://app.voicepods.com/api/v1/projects"
  -H "Authorization: YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    data: <Project Resource>
  }'

The above command returns JSON structured like this if successful:

{
  "status": "OK"
}

Creates a new Project. This endpoint expects valid JSON with a data attribute that represents the Project resource.

HTTP Request

POST https://app.voicepods.com/api/v1/projects

Pod

Pod Resource

{
  title: <string>,
  body: <string>, 
  author: <string>,
  uuid: <string>,
  voice: <string>,
  public: <boolean>
}

Get All Pods

curl "https://app.voicepods.com/api/v1/projects/<project_id>/pods"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "title": "First Pod!",
    "body": "<speak><p>Voicepods increases productivity through an easy to use API. <break time='1.5s'/> What do you think?</p></speak>",
    "published": "2018-09-03T03:33:33.000Z",
    "author": "Voicepods Team",
    "finished": true,
    "link": "https://app.voicepods.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBYQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--61a46da3edde02743c8eb18631498c54268e9191/WTIDZGUW.mp3",
    "voice": "Noah",
    "project_id": 1
  }
]

This endpoint retrieves all pods within the given project.

HTTP Request

GET https://app.voicepods.com/api/v1/projects/<project_id>/pods

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch

Get a Specific Pod

curl "https://app.voicepods.com/api/v1/projects/<project_id>/pods/<id>"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "title": "First Pod!",
  "body": "<speak><p>Voicepods increases productivity through an easy to use API. <break time='1.5s'/> What do you think?</p></speak>",
  "published": "2018-09-03T03:33:33.000Z",
  "author": "Voicepods Team",
  "finished": true,
  "link": "https://app.voicepods.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBYQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--61a46da3edde02743c8eb18631498c54268e9191/WTIDZGUW.mp3",
  "voice": "Noah",
  "project_id": 1
}

Returns a Pod Resource.

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch
ID The ID of the Pod to fetch

HTTP Request

GET https://app.voicepods.com/api/v1/projects/<PROJECT_ID>/pods/<ID>

Create a new Pod

curl "https://app.voicepods.com/api/v1/projects/<project_id>/pods"
  -H "Authorization: YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    callback_uri: <your callback uri>,
    data: <Pod Resource>
  }'

The above command returns JSON structured like this if successful:

{
  "status": "OK",
  "id": <pod_id>,
  "project_id": <project_id>
}

Creates a new Pod. This endpoint expects valid JSON with a data attribute that represents the Pod resource. We also support callback urls, where you can define a service that will recieve a POST request when the pod has been completed.

The callback request will look like this:

{
  "id": <id>,
  "url": <url to audio>
}

HTTP Request

POST https://app.voicepods.com/api/v1/projects/<PROJECT_ID>/pods

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The voicepods requested is hidden for administrators only.
404 Not Found -- The specified voicepods could not be found.
405 Method Not Allowed -- You tried to access voicepods with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The voicepod requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too fast! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.