AGNT API - Getting Started

The AGNT platform provides two complementary APIs:

  1. Remote API (https://api.agnt.gg) - Cloud-based services for user management, marketplace, and shared resources
  2. Local Backend API (http://localhost:3333) - Desktop application backend for agent execution and local operations

Quick Start

Authentication

Most API endpoints require authentication using JWT tokens. Include your token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Getting Your API Token

  1. Via Desktop App: Navigate to Settings → API Keys → Generate API Key
  2. Via Google OAuth: Authenticate through /api/users/auth/google
  3. Via Magic Link: Request a magic link via /api/users/auth/magic-link/request
curl -X POST https://api.agnt.gg/users/auth/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
const response = await fetch('https://api.agnt.gg/users/auth/magic-link/request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
  }),
});
import requests

response = requests.post(
    'https://api.agnt.gg/users/auth/magic-link/request',
    json={'email': 'user@example.com'}
)

API Architecture

Remote API (api.agnt.gg)

Handles cloud-based operations:

  • User authentication and management
  • Marketplace operations
  • Workflow sharing and publishing
  • Subscription and billing
  • Referral system
  • Email services

Base URL: https://api.agnt.gg

Local Backend API (localhost:3333)

Handles desktop application operations:

  • Agent execution and management
  • Workflow execution
  • Tool operations
  • MCP server integration
  • Speech-to-text
  • Local file operations

Base URL: http://localhost:3333/api

Common Request Patterns

Making Authenticated Requests

const token = 'YOUR_JWT_TOKEN';

// GET request
const agents = await fetch('https://api.agnt.gg/agents', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

// POST request
const newAgent = await fetch('https://api.agnt.gg/agents/save', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Agent',
    model: 'gpt-4',
    systemPrompt: 'You are a helpful assistant',
  }),
});

Handling Responses

const response = await fetch('https://api.agnt.gg/agents');

if (response.ok) {
  const data = await response.json();
  console.log(data);
} else {
  const error = await response.json();
  console.error('Error:', error.message);
}

Response Format

Success Response

{
  "success": true,
  "data": {
    /* response data */
  },
  "message": "Operation completed successfully"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": "Additional error details"
}

Rate Limiting

  • Remote API: Rate limits vary by plan (Free: 100/hour, Personal: 1000/hour, Business: 10000/hour)
  • Local API: No rate limits (runs on your machine)

Common Status Codes

Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

API Endpoints Overview

Remote API Endpoints

Local Backend Endpoints

SDK Support

For easier integration, use the official AGNT SDK:

npm install @agnt/sdk
import { AgntClient } from '@agnt/sdk';

const client = new AgntClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.agnt.gg',
});

// Use the client
const agents = await client.agents.list();

Next Steps

Support