API & integrations

An API is a way for other software to fetch data from Renewly without anyone logging in. Your developers or IT team can use it to pull your contracts into a spreadsheet, a reporting dashboard or another system.

Getting started with the API

The Renewly API lets software read your data. It cannot change anything. You can list your contracts, get the full details of one contract, download your contracts as a CSV file, and list your portfolio insights.

Every request must carry an API key. This is a long secret code that proves the request comes from your account. Treat it like a password.

Creating API keys

1. Go to Settings › API Keys. This page appears in the settings menu for workspace owners and admins.
2. If asked, click Verify with 2FA and confirm with your two-factor code. Renewly asks for a recent check before showing or creating keys.
3. Click Create API Key.
4. Under Key Name, type a name that tells you where the key will be used, for example "Finance dashboard".
5. Under Expiration, choose Never, 30 days, 90 days or 1 year.
6. Click Create Key.
7. Copy the key straight away, then click I've saved my key.

You can have up to 10 active keys at a time.

Authentication

Send your API key with every request in a header called X-API-Key:

X-API-Key: your-api-key-here

You can send it as Authorization: Bearer your-api-key-here instead if your tool prefers that. A request with a missing, wrong, revoked or expired key gets a 401 Unauthorized reply.

Available endpoints

An endpoint is one web address the API answers on. All addresses start with https://renewly.gg.

List contracts

GET /api/v1/contracts

Returns your contracts, 50 at a time by default. Add ?limit= (up to 100) and ?offset= to page through them, and ?status= to filter. If you belong to a workspace, you get that workspace's contracts. To choose a particular workspace, add ?organization_id=.

Get contract details

GET /api/v1/contracts/:id

Returns one contract with everything Renewly read from it, such as the parties, dates, values and payment terms.

Export contracts to CSV

POST /api/v1/contracts/export

Downloads your reviewed contracts as a CSV file you can open in Excel. Send a JSON body, which can be empty ({}) or include status and organization_id to filter. Exports have their own, lower limit (see below).

Portfolio insights

GET /api/v1/insights

Returns the findings from your portfolio analysis, such as renewals that need action soon or unusual spending. Each one has a type, a severity, a title and a description.

By default you get active insights. Add ?status=dismissed, ?status=resolved or ?status=all to see others, and ?limit= and ?offset= to page through them.

Webhooks

Webhooks work the other way round: Renewly sends a message to your system when something happens. You set them up in the Webhooks section of Settings › API Keys, not through an API key.

Rate limits

To keep the service fast for everyone, each API key has limits:

• Most requests: 60 per minute
• CSV exports: 10 per hour

If you go over a limit, you get a 429 Too Many Requests reply. The message tells you how many seconds to wait before trying again.

Error handling

Every reply has a standard status code that says whether it worked:

• 200 OK: it worked.
• 401 Unauthorized: the API key is missing, wrong, revoked or expired.
• 403 Forbidden: the key is valid but not allowed to do this. For example, you do not have access to that contract, or your workspace's plan does not include the API.
• 404 Not Found: the contract does not exist.
• 429 Too Many Requests: you went over a rate limit. Wait, then try again.
• 500 Internal Server Error: something went wrong on our side. If it keeps happening, contact support.

An error reply includes a short explanation, like this:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 30 seconds",
    "requestId": "..."
  }
}

If you contact support about an error, include the requestId. It helps us find what happened.

Code examples

cURL

List your contracts:

curl -s https://renewly.gg/api/v1/contracts \
  -H "X-API-Key: your-api-key-here" | jq

Get the details of one contract:

curl -s https://renewly.gg/api/v1/contracts/CONTRACT_ID \
  -H "X-API-Key: your-api-key-here" | jq

Export your contracts to a CSV file:

curl -s -X POST https://renewly.gg/api/v1/contracts/export \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{}' \
  -o contracts.csv

JavaScript (fetch)

const API_KEY = process.env.RENEWLY_API_KEY;

// List your contracts
const response = await fetch('https://renewly.gg/api/v1/contracts', {
  headers: {
    'X-API-Key': API_KEY,
  },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(body.error.message);
}

console.log(body.data.contracts);
console.log(body.data.pagination);

// Get the details of one contract
const contractId = 'your-contract-id';
const response = await fetch(
  `https://renewly.gg/api/v1/contracts/${contractId}`,
  {
    headers: {
      'X-API-Key': API_KEY,
    },
  }
);

const body = await response.json();
console.log(body.data.contract);

Security best practices

• Use one key per connection: give each tool or script its own key, so you can switch one off without breaking the others
• Set an expiry date: a key that expires stops working on its own if it is forgotten
• Replace keys now and then: create a new key, move your tool over to it, then revoke the old one
• Keep keys out of code: store them in a secrets manager or an environment setting, never written into the code itself
• Revoke a leaked key at once: go to Settings › API Keys and revoke it. Anything using it loses access immediately
• Check usage: each key shows when it was last used, and the API Usage section shows recent activity

Full documentation

For the full technical reference, see the API documentation.

Need help?

If you have questions about the API, email support at support@renewly.gg.