How does the Tettra API work

Overview

The API allows you to create new pages and page requests, search your Tettra pages, and ask questions.

How it works

API Key and Team ID

The API key is unique to your user and team and it has the same permissions as your user.

If you haven't already generated your API key, find out how to do this here. You can also find your Team ID by following the same steps.

Endpoints

Search

Returns up to 5 page results for the given search term.

URL: https://app.tettra.co/api/teams/{{team_id}}/search
HTTP Method: GET
Arguments:

• api_key - required - your API key
• query - optional - the search term; returns most recent pages if omitted

Example Request

curl -X GET \
    -H 'Content-Type: application/json' \
    --data \
    '{
        "api_key":"xxxxxxxxxxxxxxxxxx1234567890",
        "query":"Company Holidays"
    }' \
    https://app.tettra.co/api/teams/5/search

Example Response

{ 
   success: true, 
   query: "Company Holidays", 
   pages: [ 
      { 
         id: 2, 
         title: "2020 Company Holidays", 
         updated_at: "2020-06-03T17:10:24.000000Z", 
         url: "https://app.tettra.co/teams/example/pages/2020-company-holidays", 
         content: "{"blocks":[{"key":"avkfq","text":"example content","type":"unstyled","depth":0,"inlineStyleRanges":[],"entityRanges":[],"data":{}}],"entityMap":{}}", 
         owner: "Andy", 
         category: { 
            id: 1, 
            name: "Office & Ops", 
            url: "https://app.tettra.co/teams/example/categories/1" 
         } 
      } 
   ] 
}

Create Page

Publishes a new Tettra page from the given HTML content. 

URL: https://app.tettra.co/api/teams/{{team_id}}/pages
HTTP Method: POST
Arguments:

• api_key - required - your API key; this determines the author of the page 
• title - required - the title of the page
• body - required - the body of the page formatted as HTML
• category_id - optional - the category to publish the page to

Example

curl -X POST \
    -H 'Content-Type: application/json' \
    --data \
    '
    {
        "api_key":"xxxxxxxxxxxxxxxxxx1234567890",
        "title":"My Awesome Page",
        "body":"<h1>Hello World!</h1>"
    }
    ' \
    https://app.tettra.co/api/teams/2/pages

Create a Question

Publishes a new Tettra page from the given HTML content.

URL: https://app.tettra.co/api/teams/{{team_id}}/questions
HTTP Method: POST
Arguments:

• api_key - required - your API key; this determines the asker of the question
• title - required - the title of the question
• details - optional - additional details formatted as HTML
• category_id - optional - the category to ask the question in
• subcategory_id - optional - the subcategory to ask the question in (if category_id is also provided, the subcategory must be in the provided category)
• assignees - optional - array of user ids to assign the question to

Example

curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data \
    '
    {
        "api_key":"xxxxxxxxxxxxxxxxxx1234567890",
        "title":"How do I create a question via api?",
        "details":"<h1>Hello world!</h1>",
        "category_id":2,
        "assignees": [12, 22]
    }
    ' \
    https://app.tettra.co/api/teams/2/questions

Suggest a New Page

Creates a new page suggestion.

URL: https://app.tettra.co/api/teams/{{team_id}}/suggestions
HTTP Method: POST
Arguments:

• api_key - required - your API key; this determines the creator of the suggestion 
• title  - required - title of suggestion
• description  - optional - more context about the suggested page
• category - optional - the category to publish the page to
• assignable_id - optional - the id of the user to assign the suggestion

Example

curl -X POST  -H 'Content-Type: application/json' \
     --data \
     '{
          "api_key":"xxxxxxxxxxxxxxxxxx1234567890",
          "title":"A new page about something I want to know",
          "description":"A question that should be documented",
          "category":2,
          "assignable_id":22
     }' \
     https://app.tettra.co/api/teams/2/suggestions

Suggest Page Update

Creates a new suggestion to update an existing page.

URL: https://app.tettra.co/api/teams/{{team_id}}/suggestions
HTTP Method: POST
Arguments:

• api_key - required - your API key; this determines the creator of the suggestion 
• update - required - (boolean) indicates this is a suggestion for an update to an existing page (instead of a new page)
• page_id - required - the id of the page that needs updating
• description - optional - more context about the suggested change
• assignable_id - optional - the id of the user to assign the suggestion

Example

curl -X POST  -H 'Content-Type: application/json'   \
    --data \
    '{
        "api_key":"xxxxxxxxxxxxxxxxxx1234567890",
         "update":true,
         "description":"Update this outdated page",
         "page_id":2,
         "assignable_id":22
    }' \
    https://app.tettra.co/api/teams/2/suggestions

Related

• API overview