To get started with the API you'll want to get an api token.
You can see how to get an API token here: http://help.bidsketch.com/article/76-using-the-bidsketch-api
Your adventure with the Bidsketch API starts at https://bidsketch.com/api/v1
. This is the beginning of every end point.
curl https://bidsketch.com/api/v1/proposals -H 'Authorization: Token token="yourtoken"'
We use HTTP token authentication to identify and authorize accounts for the API. All you need to do as a developer is ask Bidsketch users to get their api token and pass it along in an authorization header.
Authorization: Token token="abc123abc123abc123abc123abc123"
Users can find their api tokens at [subdomain].bidsketch.com/account/api_tokens
. Keep in mind that only Admin users can manage api tokens.
We're starting this api with a nice, comfortable version 1, hence the v1/
part of the api path. This just means that you can trust that v1
will keep working the way you expect it. When we have to introduce something that could break what you have worked so hard to build, we'll bump the version of the API up one.
We limit requests for each token to 100 requests in 20 seconds.
Code | Reason | When You'll See It |
---|---|---|
200 | OK. Cool. | Successful GET , PUT , and POST requests |
204 | No Content | Successful DELETE requests |
400 | Bad Request | No API token was provided |
401 | Unauthorized | Revoked or Invalid API token |
404 | Not Found | Can't find the API resource or URL you asked for |
422 | Unprocessable Entity | Invalid data when creating or updating |
426 | Upgrade Required | The account has hit a client or proposal limit |
500 | Internal Server Error | Something went very, very wrong |
Whenever you get a 422 Unprocessable Entity
code, it'll have a json-formatted array of errors for what went wrong:
{
"errors": [
"email cannot be blank",
"first_name is far too silly",
"last_name matches first_name. Who has two first names?"
]
}
By default, we paginate collections and limit them to 100 objects per request. You can request specific pages by appending a page
parameter to the URL. You can
GET /clients.json?page=3
would get the 201st to 300th clientsGET /proposals.json?per_page=2
would get the first two proposalsGET /sections.json?page=8&per_page=1
would get a collection of only the eighth section
This API is pretty new, so we don't have any libraries available just yet. As they become available, we'll link them them here. If you've written a library for the Bidsketch API and would like to contribute, let us know at support@bidsketch.com!