Skip to main content
This reference describes the REST APIs you can use to interact with the Ghost platform.
You may want to create an API key before you start.

​
Authentication

The Ghost API uses API keys for authentication. Create and manage API keys in your platform settings. Remember that your API key is a secret! Do not share it with others or commit it to source control. API keys should be securely loaded from an environment variable or key management mechanism. If necessary, you can disable an API key if it has been compromised. API keys should be provided in the Authorization header as a Bearer token. 
Authorization: Bearer <api_key>
An example request using curl: 
curl "https://api.ghostsecurity.ai/v2/findings" \
     -H "Authorization: Bearer <api_key>"

​
Rate limits

The Ghost API is subject to request rate limits. Rate limits determine the number of times a user or client can access the Ghost API within a specified period of time. API rate limits are measaured requests per minute (RPM). All API responses contain a x-ratelimit-remaining header. When this value reaches 0, further requests will be blocked until the limit resets. The number of seconds until the limit resets is available in the x-ratelimit-reset header. 
curl https://api.ghostsecurity.ai/v2/repos \
    -H "Authorization: Bearer $GHOST_API_KEY"
* Host api.ghostsecurity.ai:443 was resolved.
> GET /v2/repos HTTP/2
> Host: api.ghostsecurity.ai
> User-Agent: curl
> Accept: */*
> Authorization: Bearer gk-******
>
* Request completely sent off
< HTTP/2 200
< content-type: application/json
< vary: Origin
< x-ratelimit-limit: 200
< x-ratelimit-remaining: 199
< x-ratelimit-reset: 55
In the above example, the client can make 199 more requests before being blocked. As a best practice, you should ensure your implementation respects these limits to avoid having requests blocked with a 429 Too Many Requests error. If you receive a 429 error, you can understand the wait time required by reading the retry-after header. You must wait at least retry-after seconds before your next request.

​
Organizations

API keys are scoped to an organization. If you belong to multiple organizations, you must create API keys within each organization.