Quickstart

This guide takes you from zero to your first response in about five minutes.

1. Activate the API in COMMITLY. Sign in to app.commitly.com, open Add-ons and click Connect on the COMMITLY Public API tile. COMMITLY shows your Client ID and Client secret right there. The API is included from the Business Edition.

   Caution

   Treat the client secret like a password. Keep it on the server side, never in a browser app or a public repository. If it leaks, click Disconnect on the tile and connect again to get new credentials.

2. Request an access token. Send your credentials to the token endpoint. The token is valid for 5 minutes.

   curl

   curl -X POST https://app.commitly.com/api/auth/token/ \
     -d grant_type=client_credentials \
     -d client_id="$COMMITLY_CLIENT_ID" \
     -d client_secret="$COMMITLY_CLIENT_SECRET"

   JavaScript

   const res = await fetch("https://app.commitly.com/api/auth/token/", {
     method: "POST",
     body: new URLSearchParams({
       grant_type: "client_credentials",
       client_id: process.env.COMMITLY_CLIENT_ID,
       client_secret: process.env.COMMITLY_CLIENT_SECRET,
     }),
   });
   const { access_token } = await res.json();

   Python

   import os, requests
   
   res = requests.post(
       "https://app.commitly.com/api/auth/token/",
       data={
           "grant_type": "client_credentials",
           "client_id": os.environ["COMMITLY_CLIENT_ID"],
           "client_secret": os.environ["COMMITLY_CLIENT_SECRET"],
       },
   )
   access_token = res.json()["access_token"]

3. Make your first call. List the categories of your company. Send the token in the Authorization header with the Bearer prefix.

   curl

   curl https://app.commitly.com/api/categories/ \
     -H "Authorization: Bearer $ACCESS_TOKEN"

   JavaScript

   const categories = await fetch("https://app.commitly.com/api/categories/", {
     headers: { Authorization: `Bearer ${access_token}` },
   }).then((r) => r.json());

   Python

   categories = requests.get(
       "https://app.commitly.com/api/categories/",
       headers={"Authorization": f"Bearer {access_token}"},
   ).json()

   The response lists every category with its id. You need these IDs whenever you create invoices or budgets.

Coding with an AI assistant?

Connect Cursor, Claude Code, VS Code or Windsurf to these docs with the public docs MCP server. Your assistant then looks up real endpoints and fields instead of guessing.

Next steps

• Authentication: token lifetime, renewal and errors.
• Data model: how categories, plans, scenarios and the forecast fit together.
• Testing: what to know before you write to a live account.