Your First API Call

The AbleTime API lets you read and write the same work your team tracks in the application. In this guide you create an API key, make your first request with curl, and read what comes back.

Before you start

You need an organization plan that includes API access, and the admin or owner role, because only admins and owners can create API keys.

Create an API key

Go to Settings → Integrations → API Keys and create a key. Give it a name, pick its grants, and optionally set an expiry date. For this walkthrough, the project.read grant is enough: it lets the key read projects and nothing else.

Copy the key when it's shown.

This the only time you see the full secret, and everything the key can do, anyone holding it can do. It is the private key and should never be stored or recorded anywhere outside of key storage or environment variables, or used in a way that exposes it to logs or public viewing.

Grants are fixed when the key is created. To change what a key can do, you create a new key and revoke the old one. Picking the right set for a real integration is covered in Choosing Grants.

Make the call

Every endpoint lives under /api/public/v2 on your AbleTime host. You can test your API key using curl:

bash

curl https://your-abletime-host/api/public/v2/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

The URL names the resource: /api/public/v2 is the API's base path, with the version in it, and /projects is the collection you're reading. The -H flag adds the Authorization header, which is how every request carries its credential: the Bearer scheme means "whoever bears this token gets its access", which is exactly why the key stays secret. Replace YOUR_API_KEY with the key you copied.

Notice what you didn't send: an organization id. Your organization comes from the credential itself, so every request is scoped to your organization automatically, and there's nothing to configure.

Read the response

You get back JSON in the envelope every list uses:

json

{
  "data": [ ... ],
  "page": {
    "limit": 50,
    "nextCursor": null
  }
}

Your projects are the objects in data, each with an id: a 26-character identifier you'll use whenever you refer to that project. The page object is for lists too long for one response; when nextCursor holds a value, there are more pages to fetch.

Fetch one record

Take an id from the list and ask for that project on its own:

bash

curl https://your-abletime-host/api/public/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace PROJECT_ID with any project that came back from your first curl request. List, then fetch by id: that pair is the shape of almost everything you'll do against the API.

If it didn't work

Errors come back as JSON too, with a message and an errorCode that say what went wrong: a missing or mis-copied key, a key without the grant the endpoint requires, or a plan without API access. Read the message first; it usually names the fix. The credential model and the full list of refusals are on Authentication.

Where to go next

To pick the right permissions for a real integration, read Choosing Grants. To mirror AbleTime data into your own system, read Keeping Data in Sync. Every endpoint, parameter, and response shape is in the API Reference.