Advice and answers from the GatherContent Team

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 which they can gain access to from their account.

What you can GET

  1. Page content (with individual field labels)
  2. Page files
  3. Page states
  4. Users
  5. Groups
  6. Projects
  7. 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":"user@domain.com", "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] =>  user@domain.com
   [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
Did this answer your question?