Make your first request

1. Create a personal API key

Follow Get API access for the dashboard steps and help if the controls are missing.

Open API keys in Substy settings and create a personal key for the agency you want to access. Your key needs Creators: read for this example. Your agency must have API access enabled, and your role must allow Use personal API keys. Contact your agency owner if the controls are unavailable.

Save the secret in your application’s secret manager or local environment. Never include it in browser code, source control, a URL, or an AI prompt.

export SUBSTY_API_URL="https://api.substy.ai"
export SUBSTY_API_KEY="YOUR_API_KEY"

2. Find the key’s agency

curl --fail-with-body "$SUBSTY_API_URL/v1/agencies" \
  --header "Authorization: Bearer $SUBSTY_API_KEY"

Successful responses contain your result in data and a request identifier in meta.requestId. Use the agency identifier returned by this request in subsequent paths.

3. List accessible creators

export SUBSTY_AGENCY_ID="YOUR_AGENCY_ID"

curl --fail-with-body \
  "$SUBSTY_API_URL/v1/agencies/$SUBSTY_AGENCY_ID/creators" \
  --header "Authorization: Bearer $SUBSTY_API_KEY"

The result includes creators accessible to the user who issued the key. A key cannot grant access to another agency or a creator that user cannot access.

Use JavaScript

const response = await fetch(
  `${process.env.SUBSTY_API_URL}/v1/agencies/${process.env.SUBSTY_AGENCY_ID}/creators`,
  { headers: { Authorization: `Bearer ${process.env.SUBSTY_API_KEY}` } }
);
const result = await response.json();
if (!response.ok) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.data);

Keep this code on your server. Before adding writes, read operation receipts and error handling.