API Reference

Introduction

The AIVY API allows developers to integrate with our platform and access its features programmatically. This documentation provides all the information you need to get started with the API, including authentication, endpoints, and examples.

Base URL

All API requests should be made to the following base URL:

https://api.aivy.ai/v1

Request Format

The API accepts request data in JSON format. Make sure to set the following headers in your requests:

              Content-Type: application/json
              Authorization: Bearer YOUR_API_KEY

Response Format

All responses are returned in JSON format. A typical response structure looks like this:

{
              "success": true,
              "data": {
              // Response data here
              },
              "meta": {
              "pagination": {
              "total": 100,
              "per_page": 10,
              "current_page": 1,
              "last_page": 10
              }
              }
              }

Error Responses

In case of an error, the API will return a JSON response with an error message and appropriate HTTP status code:

{
              "success": false,
              "error": {
              "code": "invalid_request",
              "message": "The request was invalid",
              "details": [
              "The token parameter is required"
              ]
              }
              }

Authentication

The AIVY API uses API keys for authentication. Each request must include your API key in the Authorization header.

Obtaining an API Key

To get an API key, follow these steps:

Log in to your AIVY account
Navigate to the Developer section in your dashboard
Click on "API Keys"
Click "Generate New Key"
Give your key a name and select the appropriate permissions
Click "Create API Key"

Security Note

Your API key carries many privileges, so be sure to keep it secure. Don't share your API key in publicly accessible areas such as GitHub, client-side code, or in your frontend application.

Using Your API Key

Include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

API Key Permissions

When creating an API key, you can specify the permissions it should have. Available permissions include:

read:user - Access user profile information
read:tasks - Access task information
write:tasks - Submit and manage tasks
read:staking - Access staking information
write:staking - Manage staking operations
use:ai - Use AI tools via the API

Rate Limits

To ensure the stability of the API, rate limits are applied to all endpoints. The current rate limits are:

Plan	Rate Limit	Burst Limit
Free	60 requests per minute	100 requests
Pro	300 requests per minute	500 requests
Enterprise	1000 requests per minute	2000 requests

Rate Limit Headers

Each response includes headers that provide information about your current rate limit status:

              X-RateLimit-Limit: 60
              X-RateLimit-Remaining: 59
              X-RateLimit-Reset: 1620000000

Exceeding Rate Limits

If you exceed the rate limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how long to wait before making another request.

{
              "success": false,
              "error": {
              "code": "rate_limit_exceeded",
              "message": "Rate limit exceeded. Please try again later.",
              "details": []
              }
              }

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

2xx range indicates success
4xx range indicates an error that failed given the information provided (e.g., a required parameter was omitted)
5xx range indicates an error with AIVY's servers

Common Error Codes

Status Code	Description
400 Bad Request	The request was invalid or cannot be otherwise served
401 Unauthorized	Authentication credentials were missing or incorrect
403 Forbidden	The request is understood, but it has been refused or access is not allowed
404 Not Found	The requested resource could not be found
429 Too Many Requests	You have exceeded the rate limit
500 Internal Server Error	Something went wrong on our end

Error Response Format

All error responses follow this format:

{
              "success": false,
              "error": {
              "code": "error_code",
              "message": "Human-readable error message",
              "details": [
              "Additional error details if available"
              ]
              }
              }

User Endpoints

These endpoints allow you to access and manage user information.

GET /user/profile

Retrieves the profile information of the authenticated user.

Parameters

No parameters required.

Response

{
                "success": true,
                "data": {
                "id": "usr_123456789",
                "username": "johndoe",
                "email": "john@example.com",
                "name": "John Doe",
                "avatar_url": "https://api.aivy.ai/avatars/johndoe.jpg",
                "created_at": "2023-01-15T12:00:00Z",
                "updated_at": "2023-05-20T15:30:00Z",
                "stats": {
                "tasks_completed": 42,
                "tokens_earned": 1250,
                "tokens_staked": 1000
                }
                }
                }

curl -X GET "https://api.aivy.ai/v1/user/profile" \
                -H "Authorization: Bearer YOUR_API_KEY" \
                -H "Content-Type: application/json"

const response = await
                fetch('https://api.aivy.ai/v1/user/profile', {
                method: 'GET',
                headers: {
                'Authorization': 'Bearer YOUR_API_KEY',
                'Content-Type': 'application/json'
                }
                });

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

import requests

                url = "https://api.aivy.ai/v1/user/profile"
                headers = {
                "Authorization": "Bearer YOUR_API_KEY",
                "Content-Type": "application/json"
                }

                response = requests.get(url, headers=headers)
                data = response.json()
                print(data)

AIVY API Reference