Getting Started

Getting Started with the Ringfence API

Welcome to the Ringfence API! This guide will walk you through the initial setup and basic steps to start interfacing with the Ringfence API, from account creation to token generation and making your first API request.

---

1. Purchase API Access

To begin, purchase access to the Ringfence API via Ringfence.ai. Once the purchase is complete, an account is automatically created based on the provided email address.

• Username: Your username is set as the email address associated with your purchase.

• Temporary Password: You will receive a temporary password to the email you used for registration.

• API Docs: You'll also receive a link to the API docs, where you can change the password.

---

2. Log In and Generate Your API Key

With your username and temporary password, log into your Ringfence account to generate an API key. The API key is your unique identifier, allowing secure access to the API.

1. Log In: Use your username (email address) and the temporary password sent to you. We recommend updating your password upon your first login.

2. Generate API Key:

   • Navigate to the API settings page and find the option to Generate Token/API Key.

   • Visit this endpoint to create your API token. You will be asked to authenticate using your username and password.

   • Upon generation, your API key will be provided. Store this key securely; it will be required to authenticate all API requests.

---

3. Authenticating API Requests

Each request to the Ringfence API must include your API key in the Authorization header. The API key is provided as a Bearer token.

Example of Authorization Header:

plaintext

Authorization: Bearer <your_api_key>

Sample Request Using Authorization Header (JavaScript/Node.js):

import axios from "axios";

const apiKey = "<your_api_key>";  // Replace with your actual API key

async function verifyImage() {
  const response = await axios({
    method: "POST",
    baseURL: "https://api.ringfence.ai/api/v1/images/verify",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
    data: {
      images: [
        {
          url: "https://example.com/image.png",
        },
      ],
    },
  });
  console.log(response.data);
}

verifyImage();

4. Understanding API Rate Limits and Error Handling

The Ringfence API enforces rate limits to ensure fair usage across all users and to optimize interactions with its partner service, Astica. Understanding these limits and the error codes that the API may return will help you avoid disruptions and ensure smooth usage.

Rate Limits

• General Rate Limit: The Ringfence API limits requests to a maximum of 45 requests per minute in alignment with Astica’s rate restrictions. Exceeding this limit will result in a 429 Too Many Requests error. We recommend implementing retry logic with exponential backoff if you receive this error to manage rate limits efficiently.

• Batch Validation: The Ringfence API allows users to validate up to 10 images in a single request. This batch processing capability enables efficient use of your request quota and simplifies the validation process.

---

Image Requirements

Each image provided for validation should be supplied as a URL and must be in one of the following formats:

• jpg

• jpeg

• png

• gif

Any images not conforming to these formats will be rejected, potentially resulting in a 400 Bad Request error.

Error Codes and Their Meanings

Understanding common error codes will help you diagnose issues and respond appropriately:

• 400 Bad Request: This error typically indicates a malformed request. Common causes include:

  • Incorrectly formatted parameters or JSON data.

  • Unsupported image formats (ensure your images are in jpg, jpeg, png, or gif).

  • Exceeding the limit of 10 images per request.

  Solution: Double-check your request parameters, JSON structure, and ensure all images meet the format requirements.

• 401 Unauthorized: This error means there’s an issue with your API key, possibly due to:

  • An incorrect or missing API key in the Authorization header.

  • An expired or deactivated API key.

  Solution: Verify your API key is active, correctly formatted, and included in the Authorization header as a Bearer token.

• 429 Too Many Requests: This error indicates you have exceeded the rate limit of 45 requests per minute.

  Solution: Implement retry logic with a delay, allowing time before making additional requests to avoid hitting the rate limit again.

• 500 Internal Server Error: This error signifies an issue on the server side, which may occasionally occur due to high traffic or maintenance.

  Solution: Wait a moment and try your request again. If the problem persists, contact Ringfence support for assistance.

---

Following these guidelines on rate limits, error handling, and image requirements will help ensure a smooth experience while using the Ringfence API. Refer to the Ringfence API documentation or contact the support team for additional support.