Executing Actions

This guide explains how to call actions via the Universal API.

Endpoint

GET/POST https://api.universalapi.co/action/{actionId}

Authentication

Include your credentials via headers:

curl "https://api.universalapi.co/action/act-abc123" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key"

Or query parameters:

curl "https://api.universalapi.co/action/act-abc123?userId=your-user-id&secretUniversalKey=your-secret-key"

Passing Parameters

Query String (GET)

curl "https://api.universalapi.co/action/act-abc123?name=John&count=5" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key"

Request Body (POST)

curl -X POST "https://api.universalapi.co/action/act-abc123" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key" \
  -d '{"name": "John", "count": 5}'

Response Format

Success:

{
  "success": true,
  "apiVersion": "2023-11-01",
  "data": {
    "statusCode": 200,
    "body": {
      "message": "Hello, John!"
    }
  },
  "meta": {
    "requestId": "abc-123-def",
    "statusCode": 200,
    "timestamp": "2025-01-13T12:00:00.000000",
    "executionTime": 245,
    "memoryMb": 128,
    "creditsUsed": 1
  },
  "debug": {
    "traceUrl": "https://api.universalapi.co/logs/trace/1-xxx"
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "ACTION_NOT_FOUND",
    "message": "The requested action does not exist",
    "timestamp": "2025-01-13T12:00:00.000000"
  },
  "meta": {
    "requestId": "abc-123-def",
    "statusCode": 404
  }
}

Direct Runtime Endpoint

You can also use the direct Python runtime endpoint:

curl "https://api.universalapi.co/action/python-128mb/act-abc123?name=John" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key"

This bypasses the router and calls the Python runtime directly.

Inline Code Execution

Execute Python code without creating an action:

curl -X POST "https://api.universalapi.co/action/python-128mb/inline-code" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key" \
  -d '{
    "code": "def handler(event, context):\n    return {\"message\": \"Hello!\"}",
    "event": {"name": "test"}
  }'

JavaScript Examples

Fetch API

const response = await fetch(
  "https://api.universalapi.co/action/act-abc123?name=John",
  {
    headers: {
      "X-Uni-UserId": "your-user-id",
      "X-Uni-SecretUniversalKey": "your-secret-key"
    }
  }
);
const data = await response.json();
console.log(data);

POST with Body

const response = await fetch(
  "https://api.universalapi.co/action/act-abc123",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Uni-UserId": "your-user-id",
      "X-Uni-SecretUniversalKey": "your-secret-key"
    },
    body: JSON.stringify({ name: "John", count: 5 })
  }
);
const data = await response.json();

Python Examples

requests Library

import requests

response = requests.get(
    "https://api.universalapi.co/action/act-abc123",
    params={"name": "John"},
    headers={
        "X-Uni-UserId": "your-user-id",
        "X-Uni-SecretUniversalKey": "your-secret-key"
    }
)
print(response.json())

POST Request

import requests

response = requests.post(
    "https://api.universalapi.co/action/act-abc123",
    json={"name": "John", "count": 5},
    headers={
        "X-Uni-UserId": "your-user-id",
        "X-Uni-SecretUniversalKey": "your-secret-key"
    }
)
print(response.json())

Anonymous Access

Some public actions allow anonymous access with rate limiting:

# No auth headers - rate limited to 10 requests per 24 hours
curl "https://api.universalapi.co/action/act-public-action?name=test"

Credits

• Each action execution costs 1 credit minimum
• New users receive 100 free credits
• Credits replenish monthly if below 100
• Check your balance: GET /user/credits

Error Codes

Code	Description
ACTION_NOT_FOUND	Action ID doesn't exist
ACTION_DELETED	Action was deleted
AUTHENTICATION_REQUIRED	Missing credentials
INSUFFICIENT_CREDITS	No credits remaining
RATE_LIMIT_EXCEEDED	Too many requests
ACTION_EXECUTION_FAILED	Runtime error in action

Debugging

Use the trace URL from the response to debug issues:

curl "https://api.universalapi.co/logs/trace/1-xxx-yyy" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key"

This returns detailed execution logs, timing, and any errors.

Next Steps

• Creating Actions - Build your own actions
• OAuth Integration - Access Google services
• Logs API - Query execution history