API & Integrations

Access your contract data programmatically with the Renewly API. Generate API keys, query your contracts, and integrate Renewly into your existing workflows.

Getting Started with the API

The Renewly API provides read-only access to your contract data. You can list contracts, retrieve details with extracted data, and export contracts to CSV. All requests are authenticated with API keys and rate limited to ensure fair usage.

To get started, you need a Renewly account with at least one contract, and an API key generated from your Settings page.

Creating API Keys

Generate an API key to authenticate your requests:

1. Log in to your Renewly account
2. Go to Settings → API Keys
3. Click "Create API Key"
4. Enter a descriptive name for the key (e.g., "CRM Integration" or "Reporting Dashboard")
5. Optionally set an expiration date for the key
6. Click "Create" and immediately copy the key

Authentication

Authenticate all API requests by including your API key in the X-API-Key header:

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

Every request must include this header. Requests without a valid API key will receive a 401 Unauthorized response.

Available Endpoints

The API currently supports the following read-only endpoints:

List Contracts

GET /api/v1/contracts

Returns a paginated list of all contracts accessible to your account, including personal contracts and organization contracts where you are a member.

Get Contract Details

GET /api/v1/contracts/:id

Returns full details for a specific contract, including all extracted data such as parties, dates, values, payment terms, risks, and tags.

Export Contracts to CSV

GET /api/v1/contracts/export

Exports your contracts as a CSV file. Includes party names, dates, payment terms, values, tags, status, and risk severity. Export operations have a separate rate limit (see below).

Portfolio Insights

GET /api/v1/insights

Returns portfolio-level insights including renewal timing patterns, vendor consolidation opportunities, spend anomalies, and risk trends. Each insight includes a type, severity, title, description, and actionable recommendation.

Filter by status (active, dismissed, resolved) or by insight type using query parameters.

Get Insight Details

GET /api/v1/insights/:id

Returns full details for a specific insight, including the contracts and data points that contributed to the analysis.

Rate Limits

To ensure fair usage and platform stability, the API enforces the following rate limits:

• General requests: 60 requests per minute per API key
• Export operations: 10 exports per hour per API key

When you exceed the rate limit, the API returns a 429 Too Many Requests response. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200 OK: Request succeeded
• 401 Unauthorized: Missing or invalid API key. Check that you are including the X-API-Key header with a valid key.
• 403 Forbidden: Your API key does not have access to the requested resource. The contract may belong to another user or organization.
• 404 Not Found: The requested contract does not exist.
• 429 Too Many Requests: Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying.
• 500 Internal Server Error: An unexpected error occurred. If this persists, contact support.

Error responses include a JSON body with a message field describing the issue:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "retry_after": 30
}

Code Examples

cURL

List all your contracts:

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

Get details for a specific contract:

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

Export contracts to CSV:

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

JavaScript (fetch)

const API_KEY = process.env.RENEWLY_API_KEY;

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

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

const contracts = await response.json();
console.log(contracts);

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

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

Security Best Practices

• Rotate keys regularly: Create new keys periodically and revoke old ones to limit exposure
• Never commit keys to repositories: Store API keys in environment variables or a secrets manager, never in source code
• Use environment variables: Reference keys via process.env.RENEWLY_API_KEY or equivalent in your platform
• Set expiration dates: Use key expiration to automatically disable keys after a set period
• Revoke compromised keys immediately: If a key is exposed, revoke it from Settings → API Keys right away
• Use one key per integration: Create separate keys for each service or workflow so you can revoke individually
• Monitor usage: Review your API key activity periodically to detect unexpected access patterns

Full Documentation

For the complete API reference including request and response schemas, pagination, filtering options, and webhook support, see the full API documentation.

Need Help?

If you have questions about the API or need assistance with your integration, contact our support team at support@renewly.gg.