Please note that this documentation refers to our Legacy API. To read about our latest version, visit our Developer section.
Generate your Legacy API Key
To generate a Legacy API key, head to your Personal Settings, and select the "Legacy API" found at the bottom of the API tab. From here, you can either copy and paste your Legacy API or generate a new one.
The JSON API is by far the most flexible means to pull content from your GatherContent projects and into whatever platform or CMS you are using. We use the API to build all of our own integrations and exports and are working on a means to allow you to easily share your own projects.
The API lets you pull any chunks of content out of your GatherContent account so you can process and publish your content as you like. Since it treats each field as a separate entity, it’s an incredibly flexible output for adaptive content. This guide should provide the resources and examples to get you started.
At the moment only GET functions are available with the API; 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 that they can gain access to from their account.
What you can GET
Page content (with individual field labels)
Page files
Page states
Users
Groups
Projects
Templates
Functions
Here are our available functions and their required parameters that should be sent as HTTP POST field values:
1. Users
get_me – logged in user
get_users – all visible users for given API key
get_user (id) – user with specified id
2. Groups
get_my_group – group that API user belongs to
get_groups – all visible groups for given API key
get_group (id) – group with specified id
3. Projects
get_projects – all visible projects for given API key
get_project (id) – project with specified id
4. Project pages
get_page (id) – page with specified id
get_pages_by_project (id) – all pages belonging to project with specified id
5. Files
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_state (id) – custom state with specified id
get_custom_states_by_project (id)
7. Templates
get_template (id) – template with specified id
get_templates_by_project (id)
Getting started with the API
To get started using the API you’ll need to know the API address: https://[accountname].gathercontent.com/api/0.4/
And how that syntax works with functions:
https://[accountname].gathercontent.com/api/0.4/[function_name]
e.g. https://mycompany.gathercontent.com/api/0.4/get_me
Some other things to note before getting started:
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 (“application/x-www-form-urlencoded“)
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
An example of a typical response
Here’s a quick example of JSON code returned by the function “get_me”:
{"success":true,"user":[{"id":"12345","group_id":
"456","email":"[email protected]", "first_name":"John",
"last_name":"Doe","type":"superadmin","timezone":"UTC",
"created_at":"2011-06-29 09:54:49", "updated_at":"2011-11-22
11:16:49"}]}
This can be decoded (in PHP using json_decode(); ) to:
stdClass Object (
[success] => 1
[user] => Array
(
[0] => stdClass Object
(
[id] => 12345
[group_id] => 456
[email] => [email protected]
[first_name] => John
[last_name] => Doe
[type] => superadmin
[timezone] => UTC
[created_at] => 2011-06-29 09:54:49
[updated_at] => 2011-11-22 11:16:49
)
)
)
Fetching page
The “config” field for pages is encoded using JSON and base64 for ease of transport and readability (avoiding JSON-within-JSON). Here’s how the page looks like:
stdClass Object
(
[success] => 1
[page] => stdClass Object
(
[id] => 715988
[project_id] => 20485
[name] => Example page
[parent_id] => 0
[position] => 9999
[custom_state_id] => 61406
[config] => W3sibGFiZWwiOiJDb250ZW50Iiwia(...)
[type] => page
[created_at] => 2014-01-29 17:26:18
[updated_at] => 2014-01-29 17:29:08
)
)
And here’s how the “config” field looks like after decoding:
Array
(
[0] => stdClass Object
(
[label] => Content
[hidden] =>
[elements] => Array
(
[0] => stdClass Object
(
[type] => text
[name] => el1391016384257
[required] =>
[label] => Full name
[value] => <p>GatherContent Developer</p>
[microcopy] =>
[limit_type] => words
[limit] => 0
[plain_text] =>
)
[1] => stdClass Object
(
[type] => text
[name] => el1391016385908
[required] =>
[label] => Bio
[value] => <p>Lorem ipsum dolor sit amet</p>
[microcopy] =>
[limit_type] => words
[limit] => 0
[plain_text] =>
)
)
)
[1] => stdClass Object
(
[label] => Meta
[hidden] => 1
[elements] => Array
(
)
)
)
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_ee5690d863a2
[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:
<strong>https://gathercontent-production-uploads.s3.amazonaws.com/[filename]</strong>
eg.
<strong>https://gathercontent-production-uploads.s3.amazonaws.com/130980_37_ee5695</strong>
The original filename is, as you might predict, stored in the latter field.
cURL example for command line:
curl --digest -X POST \
--user your-api-key:x https://accountname.gathercontent.com/api/0.4/get_me
curl --digest -X POST --user your-api-key:x \
--data "id=1234567" https://accountname.gathercontent.com/api/0.4/get_project