Making Your First Request

This guide will walk you through making your first request to Universal API. You'll learn how to authenticate, execute an action, and understand the response.

Prerequisites

Before you begin, make sure you have:

• A Universal API account (sign up at universalapi.co if you don't have one)
• Your User ID and Secret Universal Key from your dashboard
• A tool to make HTTP requests (like cURL, Postman, or your preferred programming language)

Step 1: Choose an Action to Execute

Universal API works through "actions" - pre-built functions that perform specific tasks. For this guide, we'll use a simple "Hello World" action with the ID act-ac6a4e471bea45dc.

You can browse available actions by visiting:

https://api.universalapi.co/action/list

Step 2: Authenticate Your Request

Universal API supports three authentication methods. Choose the one that works best for your use case:

Using HTTP Headers (Recommended)

# Using cURL with HTTP headers
curl -X GET "https://api.universalapi.co/action/act-ac6a4e471bea45dc?prompt=Hello%20world" \
  -H "X-Uni-userId: your-user-id" \
  -H "X-Uni-secretUniversalKey: your-secret-key"

// Using fetch in JavaScript
const response = await fetch('https://api.universalapi.co/action/act-ac6a4e471bea45dc?prompt=Hello%20world', {
  headers: {
    'X-Uni-userId': 'your-user-id',
    'X-Uni-secretUniversalKey': 'your-secret-key'
  }
});
const data = await response.json();
console.log(data);

# Using requests in Python
import requests

response = requests.get(
    'https://api.universalapi.co/action/act-ac6a4e471bea45dc',
    params={'prompt': 'Hello world'},
    headers={
        'X-Uni-userId': 'your-user-id',
        'X-Uni-secretUniversalKey': 'your-secret-key'
    }
)
data = response.json()
print(data)

Using Query Parameters

You can append your credentials to the URL as query parameters:

https://api.universalapi.co/action/act-ac6a4e471bea45dc?prompt=Hello%20world&userId=your-user-id&secretUniversalKey=your-secret-key

WARNING

This method exposes your credentials in URLs, which may be logged by servers or appear in browser history. Use with caution, especially with the Secret Universal Key.

Using Request Body (POST requests)

For POST requests, you can include your credentials in the JSON body:

# Using cURL with request body
curl -X POST "https://api.universalapi.co/action/act-ac6a4e471bea45dc" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello world",
    "userId": "your-user-id",
    "secretUniversalKey": "your-secret-key"
  }'

// Using fetch in JavaScript
const response = await fetch('https://api.universalapi.co/action/act-ac6a4e471bea45dc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Hello world',
    userId: 'your-user-id',
    secretUniversalKey: 'your-secret-key'
  })
});
const data = await response.json();
console.log(data);

Step 3: Understand the Response

When you execute an action, you'll receive a response in a standardized format:

{
  "success": true,
  "result": {
    "response": "Hello! How can I assist you today?"
  },
  "requestId": "req-abcdef123456",
  "executionTimeMs": 120
}

The response contains:

• success: A boolean indicating whether the request was successful
• result: The action-specific response data
• requestId: A unique identifier for this request (useful for debugging)
• executionTimeMs: The time taken to execute the action in milliseconds

If an error occurs, you'll receive a response like:

{
  "success": false,
  "error": {
    "message": "Error message",
    "code": "ERROR_CODE"
  },
  "requestId": "req-1234567890"
}

Step 4: Explore Action Information

To learn more about an action before using it, you can get its documentation:

GET https://api.universalapi.co/action/info/act-ac6a4e471bea45dc

This returns detailed information about the action, including:

• Description
• Required and optional parameters
• Response format
• Examples

Step 5: Try Different Request Formats

Universal API accepts requests in multiple formats:

Natural Language Queries

GET /api?query=What is the weather forecast for New York City?

Structured Requests

POST /api
{
  "intent": "analyze_sentiment",
  "data": {
    "text": "I absolutely love this product! Would recommend to everyone."
  }
}

Function-Like Calls

POST /api
{
  "function": "convert_currency",
  "params": {
    "amount": 100,
    "from": "USD",
    "to": "EUR"
  }
}

Step 6: Include External API Keys (Optional)

If you have your own API keys for external services, you can include them in your request:

POST /api
{
  "query": "Analyze the sentiment of recent tweets about our product",
  "apiKeys": {
    "aws": {
      "accessKeyId": "AKIAXXXXXXXXXXXXXXXX",
      "secretAccessKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "twitter": {
      "apiKey": "XXXXXXXXXXXXXXXXXXXXXXXX",
      "apiSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
  }
}

Next Steps

Now that you've made your first request, you can:

1. Browse available actions to see what else you can do
2. Learn about API key management for external services
3. Set up OAuth connections for services like Google
4. Explore the API Reference
5. Build MCP Servers for AI agents