REST API

Use the APITree REST API to access your API specifications, shares, and other APITree data programmatically. All you need is an API Token. For each token you can manage the access scopes so that only the relevant data is accessible. Our REST API lets you easily integrate APITree into your workflows like CI/CD to automatically update your API specification.

API Reference

APITree provides three APIs you can receive data from. The reference of each REST APIs is available in the HUB.

Core-API

Manage each and every aspect of your API documentations by using our REST API. The Core-API provides access to your APIs, endpoints, domain models, environments, authentication adapters, releases, and shares.

API Reference

Event-API

With the Event-API you can manage your webhooks. Webhooks are HTTP callbacks that receive notification messages for events. Webhooks enables you to easily integrate ApiTree into systems like Slack.

API Reference

User-API

The User-API provides access to your profile data. You can read your profile, update it and change your password by using the API. Create an API access token and try it out. You will love it!

API Reference

OAuth Scopes

To communicate with the APITree REST API, you'll need an API (OAuth) token with the right scopes. The required scopes depend on what you wish to achieve. You can select one or multiple scopes:

Scope	Description
`api`	Manage, import and exports your APIs
`api.readonly`	Read only access to your APIs (HTTP GET methods)
`api_page`	Manage your API pages / guides
`api_page.readonly`	Read only access to your API pages / guides (HTTP GET methods)
`api_release`	Manage your API releases / versions
`api_release.readonly`	Read only access to your API releases / versions (HTTP GET methods)
`api_share`	Manage your API shares
`api_share.readonly`	Read only access to your API shares (HTTP GET methods)
`profile`	Access and update your profile data
`webhook`	Manage your webhooks
`webhook.readonly`	Read only access to your webhooks (HTTP GET methods)

Note: You can define as many API Tokens as you want. There are no limitations.

Creating an API Token

Login to your account. Make sure your email address is verified. In the left sidebar click API Tokens. Click Create Token. Provide a name for your token, and select the scopes you wish to include:

Warning: An API Token is like a password. Keep it secret. Use environment variables instead of hardcoding your API Token into your programs.

Note: It is good practice to change your API Token on a regular schedule.

Using an API Token on the command line with curl

The created API Token must be included in every client request in the Authorization header using the Bearer schema.

To fetch all APIs of a user send the following request:

curl -X GET "https://core-api.apitree.com/api/<ACCOUNT-ID>" \
     -H "Authorization: Bearer <YOUR-API-TOKEN>"

Note: The provided example requires an API Token with the scope api or api.readonly.

Run this command to import an existing OpenAPI reference file (tree-simple.yaml) in YAML format:

curl \
     -H "Authorization: Bearer <YOUR-API-TOKEN>"
     -H "Content-Type: multipart/form-data"
     -F "body={\"type\":\"private\",\"nickname\":\"tree-api\",\"createRelease\":true,\"releaseVersion\":\"v1.0\"}"
     -F "spec=@tree-simple.yaml;type=text/yaml"
     "https://core-api.apitree.com/api/<ACCOUNT-ID>/import"

Note: The provided example requires an API Token with the scope api or api.readonly.

Alternatively, you can import your specification file as follows:

curl -X POST 'https://core-api.apitree.com/api/<ACCOUNT-ID>/import' \
     -H 'Authorization: Bearer <YOUR-API-TOKEN>' \
     -H 'Content-Type: multipart/form-data; boundary=4f8b3320cc2183ab128396' \
     --data-raw '--4f8b3320cc2183ab128396
Content-Disposition: form-data; name="body"
Content-Type: application/json

{"type":"private","nickname":"tree-api","createRelease":true,"releaseVersion":"v1.0"}
--4f8b3320cc2183ab128396
Content-Disposition: form-data; name="file"; filename="tree-simple.yaml"
Content-Type: text/yaml

swagger: "2.0"
info:
  title: Tree API
  description: This is our example `Tree-API` (simplified version). It provides simple CRUD methods for managing trees.
  contact:
    name: APITree
    email: support@apitree.com
  license:
    name: GNU General Public License (GPL)
    url: https://opensource.org/licenses/gpl-license
  version: 1.0.0
  x-tags:
  - example
  - tree
host: localhost
basePath: /
schemes:
- https
paths:
  /api/tree:
    get:
      tags:
      - tree
      description: Get all trees
      operationId: api-tree-get
      responses:
        200:
          description: An array of trees
          schema:
            $ref: "#/definitions/TreeList"
    post:
      tags:
      - tree
      description: Creates a new tree
      operationId: api-tree-post
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: "#/definitions/Tree"
      responses:
        400:
          description: Invalid data supplied
        201:
          description: Created
          schema:
            $ref: "#/definitions/Tree"
      security:
      - oauth2:
        - tree
definitions:
  TreeList:
    type: object
    required:
      - totalItems
      - trees
    properties:
      totalItems:
        type: integer
      trees:
        type: array
        items:
          $ref: "#/definitions/Tree"
  Tree:
    type: object
    required:
      - name
      - condition
    properties:
      name:
        type: string
        description: Name of the tree
      condition:
        type: integer
        format: int32
        minimum: 1
        maximum: 5
        description:  |-
          Condition of the tree summarized in five classes:
          `5-EXCELLENT`: tree is without any visible symptoms
          `4-GOOD`: no apparent problem with
          `3-FAIR`: minor problems with
          `2-POOR`: major problems with
          `1-VERY POOR`: extreme problems
      countryCode:
        type: string
        description: "Country the tree is from as ISO-3166 2-letter country code"
      plantedAt:
        type: string
        description: Date the tree was planted - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
        format: date-time
        readOnly: true
securityDefinitions:
  oauth2:
    type: oauth2
    description: JWT token
    flow: application
    tokenUrl: https://auth.apitree.com/oauth2/token
    scopes:
      tree: View and manage trees
      tree.readonly: Read only access to tree resources
tags:
- name: tree
  description: Tree endpoints
--4f8b3320cc2183ab128396--'

Note: The provided example requires an API Token with the scope api.

REST API

API Reference

Core-API

Event-API

User-API

OAuth Scopes

Creating an API Token

Using an API Token on the command line with curl

Integrate our REST API for an always up-to-date API documentation