CloudConvert API Essential Guide

What type of API does CloudConvert provide?

Based on the search results provided, CloudConvert appears to have a REST API. Here are the key points:

API Type

CloudConvert has a REST API. The documentation refers to it as the "CloudConvert API" and provides details on how to make REST-style HTTP requests to the API endpoints.

Key Characteristics

• The API uses standard HTTP methods like GET, POST, PUT, DELETE for different operations.
• It has a base URL of https://api.cloudconvert.com/v2.
• Requests are authenticated using OAuth 2.0 or API keys.
• The API returns standard HTTP status codes for responses.
• It supports JSON as the data format for requests and responses.

Additional Information

• CloudConvert provides official SDKs for multiple programming languages including PHP, Node.js, Python, Ruby, Java, and .NET.
• There's a sandbox API available for testing and development purposes.
• The API documentation includes a Job Builder tool for trying out requests using a graphical interface.

Best Practices

• Use the sandbox API for development and testing to avoid consuming credits.
• Implement proper error handling as the API returns standard HTTP error codes.
• Consider using one of the official SDKs for easier integration if your programming language is supported.

In summary, CloudConvert offers a modern REST API that follows standard REST conventions and best practices, making it relatively straightforward to integrate with various applications and services.

Does the CloudConvert API have webhooks?

Yes, the official CloudConvert API does have webhooks. Here are the key points about CloudConvert's webhook functionality:

Webhook Support

CloudConvert provides webhook support to notify your application about the status of jobs.

Available Events

You can subscribe to the following types of events:

• job.failed: Triggered when a job fails
• job.finished: Triggered when a job is completed successfully

Creating Webhooks

You can create webhooks using the API or manage them through the CloudConvert dashboard. To create a webhook via API, you need to:

1. Use the endpoint: POST https://api.cloudconvert.com/v2/webhooks
2. Provide the webhook URL and the events you want to subscribe to in the request body

Example request:

{
  "url": "https://mywebhook/cloudconvert",
  "events": [
    "job.failed",
    "job.finished"
  ]
}

Webhook Management

• You can list your webhooks using: GET https://api.cloudconvert.com/v2/users/me/webhooks
• To delete a webhook, use: DELETE https://api.cloudconvert.com/v2/webhooks/{ID}

Security and Error Handling

1. Webhooks are cryptographically signed for security. You should validate the signature to ensure the webhook comes from CloudConvert.
2. CloudConvert will retry failed webhook deliveries up to 3 times.
3. If your webhook URL returns an HTTP 410 (Gone) error, the webhook will be automatically disabled.

Best Practices

1. Use webhooks for asynchronous processing, especially for long-running jobs like video encoding.
2. Implement proper error handling and signature validation for your webhook endpoint.
3. Monitor your webhook status through the CloudConvert dashboard or API to ensure they're functioning correctly.

By using webhooks, you can create more efficient and responsive applications that react to job statuses in real-time, without the need for constant polling.

Rate Limits and other limitations

Here are the key points about the API Rate Limits of the CloudConvert API:

Rate Limiting

• Some endpoints enforce dynamic rate limiting [1].
• Rate limited endpoints return the X-RateLimit-Limit and X-RateLimit-Remaining headers [1].
• If the rate limit is reached, a 429 error is returned along with a Retry-After header indicating how long to wait before the next request [1].

Specific Limits

• The API documentation does not specify exact numeric rate limits for most endpoints.
• Creating tasks and creating jobs are mentioned as endpoints that have rate limiting, but specific limits are not provided [1].

Free Tier Limits

• The free tier allows up to 25 conversions per day [2].

Paid Plans

• Paid plans offer higher limits, including:
  • Unlimited* file size
  • Unlimited* processing time
  • Unlimited* concurrent tasks
  • High priority processing [2]

Best Practices

• Monitor the rate limit headers to stay within allowed limits.
• Implement backoff and retry logic when receiving 429 errors.
• Consider upgrading to a paid plan for higher limits if needed.

Key Considerations

• Rate limits are dynamic and may vary by endpoint.
• The sandbox API allows unlimited jobs/tasks but only with whitelisted files [1].
• Specific numeric limits are not publicly documented, likely to allow flexibility.

In summary, while CloudConvert implements rate limiting on its API, the exact limits are not publicly specified. Users should monitor the rate limit headers, handle 429 errors appropriately, and consider paid plans for higher limits if needed. The free tier has a clear limit of 25 conversions per day, but paid plans offer much higher or "unlimited" usage for most aspects.

Latest API Version

The most recent version of the CloudConvert API is Version 2 (v2). Here are the key points about the CloudConvert API v2:

API Endpoint

The base API endpoint for v2 is:

https://api.cloudconvert.com/v2

Key Points

• This is the current production version of the CloudConvert API.
• It uses the /v2 prefix in the API URLs.
• There is also a Sandbox API available for testing, with the base URL:

  https://api.sandbox.cloudconvert.com
  

  The Sandbox API allows unlimited jobs without consuming credits, but only supports a limited set of whitelisted files.

Region Endpoints

CloudConvert offers region-specific endpoints:

• https://api.cloudconvert.com - Automatically selects nearest region
• https://eu-central.api.cloudconvert.com - EU Central region
• https://us-east.api.cloudconvert.com - US East region

Authentication

• Uses OAuth 2.0 for authentication
• Supports authorization code grant flow and implicit grant flow
• Access tokens can be obtained via https://cloudconvert.com/oauth/token

SDKs

Official SDKs are available for:

• PHP
• Node.js
• Python
• Ruby
• Java
• .NET

Best Practices

• Use the Sandbox API for development and testing
• Utilize region-specific endpoints if needed for performance
• Take advantage of the official SDKs for easier integration
• Refer to the API documentation for detailed endpoint information and request formats

How to get a CloudConvert developer account and API Keys?

Here are the key steps to get a developer account for CloudConvert and create an API integration:

1. Sign up for a CloudConvert account:

   • Go to https://cloudconvert.com and click "Sign Up" to create a free account.

2. Get your API key:

   • After signing in, go to your Dashboard and click on "API" in the left sidebar.
   • You'll see your API key listed there. This is what you'll use to authenticate API requests.

3. Set up your development environment:

   • CloudConvert provides official SDKs for PHP, Node.js, Python, Ruby, Java and .NET.
   • Install the SDK for your preferred language using the package manager (e.g. npm, pip, etc).

4. Configure the SDK with your API key:

   • Use the API key to initialize the SDK in your code. For example in PHP:

   $cloudconvert = new CloudConvert([
       'api_key' => 'YOUR_API_KEY', 
       'sandbox' => false
   ]);

5. Test the API:

   • Try making a simple API call to verify your integration is working.
   • The quickstart guide provides example code for common operations.

6. Use the Sandbox API for development:

   • CloudConvert provides a Sandbox API for testing without using credits.
   • Use the sandbox base URL: https://api.sandbox.cloudconvert.com

7. Review the API documentation:

   • Refer to the full API docs at https://cloudconvert.com/api/v2 for details on all endpoints and options.

What can you do with the CloudConvert API?

Here are the key data models you can interact with using the CloudConvert API:

Jobs

• Create jobs consisting of multiple tasks
• Get job status and details
• Cancel jobs
• Delete jobs

Tasks

• Create different types of tasks within a job:
  • Import tasks (e.g. import from URL, S3, Azure, etc.)
  • Convert tasks (convert files between formats)
  • Optimize tasks (compress PDFs, images, etc.)
  • Capture website tasks (save websites as PDF/images)
  • Export tasks (export to URL, S3, Azure, etc.)
• Get task status and details
• Cancel individual tasks

Files

• Upload input files
• Download output files
• Get file metadata

Webhooks

• Create webhook endpoints to receive notifications
• Manage webhook subscriptions

Users

• Get user information and credits

Formats

• Get information on supported file formats and conversions

Regions

• Select specific processing regions

OAuth

• Authenticate and authorize API access using OAuth 2.0

The API allows you to programmatically manage the entire file conversion workflow - from importing files, to processing them with various tasks, to exporting the results. The job and task models provide a flexible way to chain together multiple operations.