First request

This quick start will guide you through making your first API call to the Synthesio API.

We will be using the Python programming language as well as the requests library to make HTTP requests, so make sure these are installed.

All the code blocks below can be copy-pasted one after the other in a file before running it, but we will go through them step by step to explain what is happening.

1. Set up#

First, we need to import the requests library and set up some variables with your Synthesio credentials.

• USERNAME and PASSWORD are your Synthesio user account credentials; the username is usually your email address.
• CLIENT_ID and CLIENT_SECRET are your Synthesio API credentials that should have been provided to you upon request.
• PROJECT_ID is the ID of the project you want to query (6 digits).

import requests

USERNAME = "_YOUR_USERNAME_"
PASSWORD = "_YOUR_PASSWORD_"
CLIENT_ID = "_YOUR_CLIENT_ID_"
CLIENT_SECRET = "_YOUR_CLIENT_SECRET_"
PROJECT_ID = "_YOUR_PROJECT_ID_"

2. Get an access token#

Using these credentials, we can now request an access token from the Synthesio Security API. This token is valid for a few hours and can be used to authenticate all subsequent requests.

token_resp = requests.post(
    "https://rest.synthesio.com/security/v2/oauth/token",
    data={
        "grant_type": "password",
        "username": USERNAME,
        "password": PASSWORD,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "read",
    },
)
token_resp.raise_for_status()
token = token_resp.json()["access_token"]

3. Make a Search request#

The simplest request we can make is one with an empty filter set, which will match all the mentions in the project.

resp = requests.post(
    f"https://api.synthesio.com/v1/projects/{PROJECT_ID}/mentions/_search",
    headers={"Authorization": f"Bearer {token}"},
    json={"filters": {}},
)
resp.raise_for_status()
data = resp.json()

print("found:", data["total"])
print("returned:", len(data["mentions"]))
print("first mention date:", data["mentions"][0]["date"])

Result#

If everything went well, you should see an output similar to this:

found: 123456
returned: 10
first mention date: 2026-06-17T09:44:00Z

Troubleshooting#

Unauthorized (401) error

requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://rest.synthesio.com/security/v2/oauth/token

This means that the credentials you provided are invalid. Double-check your username, password, client ID, and client secret.

Forbidden (403) error

requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://api.synthesio.com/v1/projects/123456/mentions/_search

This means that you're not allowed to access the project you specified. Double-check that the PROJECT_ID variable is set to a project that exists and that you have access to.