# Getting started with the API

The Success.co API lets your own scripts, dashboards and tools read and change the same data you see in the app, from Rocks and Issues to Scorecard numbers. This guide gets you from no key to your first working request in a few minutes.

URL: https://www.success.co/docs/guides/api-getting-started  
Published: 2026-11-12

## What you can build

The API is a single [GraphQL](https://graphql.org/learn/) endpoint. Anything you can see in Success.co (Rocks, To-dos, Issues, Headlines, Scorecards, meetings, teams and people) you can read, and most of it you can create and update too.

Teams use it to:

- Pull Scorecard numbers into Power BI, Looker or a spreadsheet.
- Push a number into a Scorecard every week from another system, such as weekly revenue from your accounting tool.
- Create Issues or To-dos automatically, for example from a support ticket or a form.
- Build an internal dashboard that shows Rocks and their Milestones across teams.

If you'd rather not write code, the [Zapier integration](https://www.success.co/docs/guides/zapier) covers many of these without it.

## Create an API key

API keys belong to you, in one company. A key can see and change exactly what you can in the app, nothing more.

1. In Success.co, open **Settings**, then **Personal**, then **API Keys**.
2. Click **Create API Key** and give it a label you'll recognize later, such as "Power BI export".
3. Copy the key straight away. It's only shown once.

The same page shows your **company ID**, which you'll need when you create things. You can also get it from the API (see [Who am I?](#who-am-i) below).

> **Note:** **Keep your key secret.** Anyone who has it can act as you. Keep it on a server or in a secrets manager, never in a web page, a public repository or a spreadsheet you share. If a key leaks, delete it on the API Keys page and create a new one. A deleted key stops working straight away.

## Make your first request

Every request is an HTTP `POST` to the same address, with your key in the `Authorization` header:

```bash
curl https://www.success.co/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ teams { nodes { id name isLeadership } } }"}'
```

Your key already starts with `suc_api_`. Send it exactly as you copied it, after `Bearer `.

The answer is JSON, with what you asked for under `data`:

```json
{
  "data": {
    "teams": {
      "nodes": [
        { "id": "0b7e5f6a-3c2d-4e1f-9a8b-7c6d5e4f3a21", "name": "Leadership Team", "isLeadership": true },
        { "id": "6c1e2a40-0b1d-4f43-9f7e-1d6f0c3a2b55", "name": "Sales", "isLeadership": false }
      ]
    }
  }
}
```

The same request in JavaScript (Node 18 or later, or any modern browser tool):

```js
const response = await fetch('https://www.success.co/graphql', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUCCESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `query { teams { nodes { id name isLeadership } } }`,
  }),
})

const { data, errors } = await response.json()
if (errors) throw new Error(errors.map((e) => e.message).join('\n'))
console.log(data.teams.nodes)
```

And in Python, with the `requests` library:

```python
import os
import requests

response = requests.post(
    "https://www.success.co/graphql",
    headers={"Authorization": f"Bearer {os.environ['SUCCESS_API_KEY']}"},
    json={"query": "query { teams { nodes { id name isLeadership } } }"},
)
body = response.json()
if "errors" in body:
    raise RuntimeError(body["errors"])
print(body["data"]["teams"]["nodes"])
```

## Who am I?

Two handy fields tell you who the key belongs to and which company it works in. Use them instead of hard-coding IDs:

```graphql
query {
  currentUserId
  currentCompanyId
}
```

Your user ID is different in each company you belong to, so look it up per company rather than copying it from one to another.

## How answers are shaped

A few patterns repeat across the whole API. Once you know them, every object works the same way.

- **Lists** are plural (`todos`, `rocks`, `issues`) and return the matching items under `nodes`, plus `totalCount` and `pageInfo` for paging. See [Reading data](https://www.success.co/docs/guides/api-reading-data).
- **Single items** are singular and take an ID: `todo(id: "...")`, `rock(id: "...")`.
- **Related items** are fields on the item. A To-do has `team`, `user` and `todoStatus`; a team has `todos`, `issues` and `usersOnTeams`.
- **Field names are camelCase**: `dueDate`, `teamId`, `createdAt`.
- **Deleted items are still there**, marked with `stateId: "DELETED"`. Filter on `stateId: { equalTo: "ACTIVE" }` to see what people see in the app.
- **Descriptions are HTML.** Fields like `desc` on Rocks, To-dos and Issues, and `text` on comments, hold the same rich text as the app, such as `<p>Call the bank</p>`.
- **Dates** without a time (`dueDate`, `startDate`) are `YYYY-MM-DD`. Timestamps (`createdAt`, `updatedAt`) are ISO 8601 in UTC.

## The full schema

These guides cover what most integrations need. For every type, field and argument, browse the schema on Apollo Studio, or point any GraphQL tool (Insomnia, Postman, Altair, GraphiQL) at `https://www.success.co/graphql` with your key: the API supports introspection, so the tool can autocomplete your queries.

[Browse the full schema](https://studio.apollographql.com/public/Successco-API/variant/current/home)

## Next steps

- [Reading data](https://www.success.co/docs/guides/api-reading-data): filter, sort and page through lists.
- [Creating and updating data](https://www.success.co/docs/guides/api-creating-and-updating-data): add To-dos, close Issues, update Rocks.
- [Data model](https://www.success.co/docs/guides/api-data-model): what each object holds and how they connect.
- [Recipes](https://www.success.co/docs/guides/api-recipes): complete examples for common jobs, like a weekly Scorecard number.
- [Errors and limits](https://www.success.co/docs/guides/api-errors-and-limits): what can go wrong and how to fix it.

Building something other companies will connect to, rather than a tool for your own team? Talk to us at support@success.co about OAuth, so each company can connect without sharing a key.