Getting started

Inter’s public API is built on GraphQL. It’s the same API our own applications run on, so anything you can do in the product you can do through the API. If GraphQL is new to you, the official GraphQL documentation is a good place to start, and Apollo’s introduction to the basics fills in the rest.

Authentication

If you’re building an application for other people to use, go with OAuth2. Once the flow completes and you have an access token, pass it with the header Authorization: Bearer . OAuth2 authentication

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data '{ "query": "{ issues { nodes { id title } } }" }' \
  https://api.inter.app/graphql

Personal API keys

For personal scripts, an API key is the quickest way in. Create and manage keys under Security & access in your account settings.

To authenticate your requests, pass the key with header: Authorization:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: <Replace this with your API Key>" \
  --data '{ "query": "{ issues { nodes { id title } } }" }' \
  https://api.inter.app/graphql

Error handling

Errors come back in a standard GraphQL errors array. Each error object carries a message describing what went wrong, a path array pointing to the part of the query that failed, and extensions with additional context such as error codes or validation details.

Check the errors array before assuming success. A GraphQL query can partially succeed with a 200 HTTP status, returning data for some fields and errors for others. Watch HTTP status codes for server errors (5xx) and handle rate limits correctly. A strongly typed GraphQL client catches validation errors while you develop, and validating required fields up front saves you from null value errors at runtime.

Inter SDK

The Inter SDK wraps the GraphQL schema and gives you typed access to every model and mutation. It’s written in TypeScript, so all operations are strongly typed end to end. We recommend it for most integrations.

First requests

Once your client is set up, you can start making queries (read) and mutations (write) against the API.

Queries and mutations

To get information about the authenticated user, use the viewer query:

query Me {
  viewer {
    id
    name
    email
  }
}

Issues, like most other objects, belong to a team, so you first need the ID of the team you want to work with:

query Teams {
  teams {
    nodes {
      id
      name
    }
  }
}

With the team ID in hand, you can fetch its issues. Let’s include some issue metadata in the same request:

query Team {
  team(id: "9cfb482a-81e3-4154-b5b9-2c805e70a02d") {
    id
    name
    issues {
      nodes {
        id
        title
        description
        assignee {
          id
          name
        }
        createdAt
        archivedAt
      }
    }
  }
}

A single issue can be fetched by id:

query Issue {
  issue(id: "INT-123") {
    id
    title
    description
  }
}

Creating and editing issues

To create a new issue, use a mutation:

mutation IssueCreate {
  issueCreate(
    input: {
      title: "New exception"
      description: "More detailed error report in markdown"
      teamId: "9cfb482a-81e3-4154-b5b9-2c805e70a02d"
    }
  ) {
    success
    issue {
      id
      title
    }
  }
}

If the call succeeds ( success: true ), the response includes the new issue’s id and title .

After creating an issue, the next thing you usually want is to update it. The issueUpdate mutation takes an input with whatever fields you want to change. The id can be either the uuid from the creation response or the shorthand form like INT-123 below.

mutation IssueUpdate {
  issueUpdate(
    id: "INT-123",
    input: {
      title: "New Issue Title"
      stateId: "NEW-STATE-ID",
    }
  ) {
    success
    issue {
      id
      title
      state {
        id
        name
      }
    }
  }
}

Accessing images

Images and other assets uploaded to Inter sit behind authentication, so only authenticated users can view them. The same applies through the API: displaying an image outside the Inter application requires regular authentication" class="external"> API authentication (OAuth or API keys). If your application shows these images to end users, download them and serve them from your own environment.

Adding mentions in Markdown

Inside the Inter application, you mention users, issues, projects, and other resources by typing @ and picking from the list.

Through the API, a mention is just the plain URL of the resource in your Markdown. For example:

https://inter.app/yourworkspaceurl/profiles/someuser what do you think about
https://inter.app/yourworkspaceurl/issue/INT-123/some-issue here?

Will convert into:

@user , what do you think about , @INT-123 some issue , here?

Where the bolded segments are mentions.

Adding collapsible sections in Markdown

For collapsible sections in an issue, comment, or document, use +++ [some section title] to start the section and +++ to end it.

+++ Section title
Markdown content (initially hidden)
+++

Fetching updates

If your application displays Inter data and you want it to stay close to realtime, you have a few options. To keep API usage reasonable, pick the approach that fits how much data you’re watching.

Say you’re displaying a large number of issues and want them to stay current:

Do:

• Register a programmatic webhook and receive updates for every issue in the team. When a change comes in, update that issue. OAuth applications can register webhooks automatically.
• If you have to poll, order the results by most recently updated first. The Pagination section shows how.
• Filter issues in the GraphQL request itself rather than fetching everything and filtering in code.

Don’t:

• Poll each issue individually. There’s no case where this is needed, and your application will likely hit the rate limit.

If you have questions along the way, the api channel in our community is the fastest place to get answers.

Other examples

Queries

There are many ways to fetch issues. A common one is getting all issues assigned to a user.

First, find the user’s id:

query {
  users {
    nodes {
      name
      id
    }
  }
}

Then use the assignedIssues field on User:

query {
  user(id: "USERID") {
    id
    name
    assignedIssues {
      nodes {
        id
        title
      }
    }
  }
}

The same pattern works with workflowStates, which represent the status fields of a team:

query {
  workflowStates {
    nodes {
      id
      name
    }
  }
}
query {
  workflowState(id: "WORKFLOW_ID") {
    issues {
      nodes {
        title
      }
    }
  }
}

Archived resources

Paginated responses hide archived resources by default. Pass includeArchived: true as a query parameter to include them.

Support

If you run into problems or have questions or suggestions, join our community or send us a note ( hello@inter.app ). Both options are also available through the user menu in the Inter application.