How do I use the API?
Note: We're working on developing better documentation and further features for our API. If you have any questions or suggestions, please email us .
Introduction
At the moment only GET functions are available; you can get users, companies, projects, pages and files within your account. All data is returned as JSON.
You should note that each user has a unique API key and can only access data which they can gain access to from their account. For example, if you invite a contributor to one specific project, their API key will only give access to information within that project.
Breakdown
- Users
- Companies
- Projects
- Pages Content
- Files
- Custom states
Functions
Here are our available functions and their required parameters.
1. Users
- get_me – logged in user
- get_users – all visible users for given API key
- get_user (id) – user with specified id
2. Companies
- get_my_company – company that API key is assigned to
- get_companies – all visible companies for given API key
- get_company (id) – company with specified id
3. Projects
- get_projects – all visible projects for given API key
- get_project (id) – project with specified id
- get_projects_by_company (id) – all projects belonging to company with specified id
4. Project pages
- get_pages – all visible pages for given API key
- get_page (id) – page with specified id
- get_pages_by_project (id) – all pages belonging to project with specified id
5. Files
- get_files – all visible files for given API key
- get_file (id) – file with specified id
- get_files_by_project (id) – all files belonging to project with specified id
- get_files_by_page (id) – all files belonging to page with specified id
6. Custom states
- get_custom_states - all visible custom states for given API key
- get_custom_state (id) - custom state with specified id
- get_custom_states_by_project (id)
Example
Here is quick example of JSON code returned by the function “get_me”:
{"success":true,"user":[{"id":"12345","email":"user@domain.com", "first_name":"John","last_name":"Doe","type":"superadmin","timezone":"UTC", "language":"en-uk","gender":"1","add_to_all_projects":"N","created_at":"2011-06-29 09:54:49", "updated_at":"2011-11-22 11:16:49","company_id":"456"}]}
...can be decoded (in PHP using json_decode(); ) to:
stdClass Object (
[success] => 1
[user] => Array
(
[0] => stdClass Object
(
[id] => 12345
[email] => user@domain.com
[first_name] => John
[last_name] => Doe
[type] => superadmin
[timezone] => UTC
[language] => en-uk
[gender] => 1
[add_to_all_projects] => N
[created_at] => 2011-06-29 09:54:49
[updated_at] => 2011-11-22 11:16:49
[company_id] => 456
)
)
)
A few things to remember
- Digest Authentication is required, you can't use Basic Authentication
- only POST requests are enabled, all parameters are sent as POST fields with the request
- user authentication is based on the api_key – 64 character random string – you can find it by clicking “Settings” tab after logging in
- password has to be lowercase “x”
- only JSON sent in response
API address:
https://[accountname].gathercontent.com/api/0.2.1/
API syntax:
https://[accountname].gathercontent.com/api/0.2.1/[function_name]
eg. https://mycompany.gathercontent.com/api/0.2.1/get_companies
Downloading files:
After fetching file(s) using one of the functions from section 5 you will get something like this in response:
stdClass Object ( [success] => 1
[file] => Array ( [0] => stdClass Object ( [id] => 789
[page_id] => 234
[filename] => 130980_37_ee56957bc25f5045a34188ff90d863a2 [original_filename] => Photo1.jpg
[fieldname] => File-attachment
[size] => 0
[created_at] => 2011-06-29 21:55:35
[updated_at] => 2011-06-29 21:55:35
)
)
)
You will notice that there are fields called “filename” and “original_filename”. To fetch the file you will use the former field, based on the syntax below:
https://gathercontent.s3.amazonaws.com/[filename]
eg.
https://gathercontent.s3.amazonaws.com/130980_37_ee56957bc25f5045a34188ff90d863a2
The original filename is, as you might predict, stored in the latter field.