API Reference

Complete reference for all ERA Agent API endpoints.

Base URL

https://anewera.dev

Endpoints

POST /api/execute

Execute code in a one-shot session (non-persistent).

Request Body:

{
  "language": "python" | "node" | "typescript" | "go" | "deno",
  "code": "string",
  "timeout_ms": 30000  // optional, default 30000
}

Response:

{
  "session_id": "string",
  "stdout": "string",
  "stderr": "string",
  "exit_code": number,
  "execution_time_ms": number
}

Example:

curl -X POST https://anewera.dev/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(\"Hello World\")"
  }'

---

POST /api/sessions

Create a new persistent session.

Request Body:

{
  "language": "python" | "node" | "typescript" | "go" | "deno",
  "persistent": boolean,           // optional, default true
  "session_id": "string",          // optional, custom session ID
  "data": object,                  // optional, custom metadata
  "metadata": object               // optional, additional metadata
}

Response:

{
  "id": "string",
  "created_at": "ISO 8601 datetime",
  "last_run_at": "ISO 8601 datetime",
  "language": "string",
  "persistent": boolean,
  "file_count": number,
  "total_size_bytes": number,
  "metadata": object,
  "data": object
}

Example:

curl -X POST https://anewera.dev/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "persistent": true,
    "session_id": "my-session",
    "data": {"user": "developer"}
  }'

---

GET /api/sessions

List all active sessions.

Response:

{
  "sessions": [
    {
      "id": "string",
      "created_at": "ISO 8601 datetime",
      "last_run_at": "ISO 8601 datetime",
      "language": "string",
      "persistent": boolean,
      "file_count": number,
      "total_size_bytes": number
    }
  ],
  "count": number
}

Example:

curl https://anewera.dev/api/sessions

---

GET /api/sessions/{id}

Get session metadata and status.

Response:

{
  "id": "string",
  "created_at": "ISO 8601 datetime",
  "last_run_at": "ISO 8601 datetime",
  "language": "string",
  "persistent": boolean,
  "file_count": number,
  "total_size_bytes": number,
  "metadata": object,
  "data": object,
  "files": [
    {
      "path": "string",
      "size": number,
      "modified_at": "ISO 8601 datetime"
    }
  ]
}

Example:

curl https://anewera.dev/api/sessions/my-session

---

POST /api/sessions/{id}/run

Execute code in an existing session.

Request Body:

{
  "code": "string",
  "timeout_ms": 30000,     // optional, execution timeout
  "update_data": object,   // optional, merge into session data
  "env": {                 // optional, environment variables (NOT persisted)
    "API_KEY": "string",
    "DATABASE_URL": "string"
  }
}

Default Environment Variables:

ERA Agent automatically provides these environment variables:

• ERA_SESSION: Always set to "true"
• ERA_SESSION_ID: The session ID
• ERA_LANGUAGE: The language runtime (python, node, typescript, go, deno)

Response:

{
  "stdout": "string",
  "stderr": "string",
  "exit_code": number,
  "execution_time_ms": number,
  "files_modified": number
}

Example:

curl -X POST https://anewera.dev/api/sessions/my-session/run \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os; print(f\"Session: {os.environ.get('\''ERA_SESSION_ID'\'')}\"); print(f\"API Key: {os.environ.get('\''API_KEY'\'')}\")",
    "env": {
      "API_KEY": "secret123"
    }
  }'

⚠️ Important: Environment variables are NOT persisted. You must pass them with every /run request.

→ See Environment Variables Guide for complete documentation

---

POST /api/sessions/{id}/stream

Execute code with real-time streaming output using Server-Sent Events (SSE). Perfect for LLM generation, progress tracking, and long-running tasks.

Request Body:

{
  "code": "string",
  "timeout": 30,           // optional, execution timeout in seconds
  "env": {                 // optional, environment variables
    "API_KEY": "string"
  }
}

Response: Server-Sent Events stream

SSE Event Format:

event: stdout
data: {"type":"stdout","content":"Line 1\n"}

event: stdout
data: {"type":"stdout","content":"Line 2\n"}

event: stderr
data: {"type":"stderr","content":"Error message\n"}

event: done
data: {"type":"done","exit_code":0,"duration":"5.23s"}

Event Types:

• stdout - Standard output line
• stderr - Standard error line
• done - Execution complete (includes exit_code and duration)
• error - Execution error

Example (curl with SSE parsing):

# Simple streaming example
curl -X POST https://anewera.dev/api/sessions/my-session/stream \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import time; [print(f\"Processing {i}\") or time.sleep(0.5) for i in range(5)]"
  }'

Example (JavaScript with EventSource):

// Note: EventSource doesn't support POST, so use fetch with streaming
const response = await fetch('https://anewera.dev/api/sessions/my-session/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: 'import time\\nfor i in range(10):\\n    print(f"Token {i}")\\n    time.sleep(0.2)'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'stdout') {
        console.log(data.content);
      }
    }
  }
}

Use Cases:

• LLM Generation: Stream tokens in real-time
• Progress Tracking: Show progress bars and status updates
• Long Computations: Monitor long-running tasks
• Log Monitoring: Real-time log streaming

---

POST /api/sessions/{id}/duplicate

Clone an existing session with all its files and state.

Request Body:

{
  "new_id": "string",      // optional, custom ID for clone
  "data": object           // optional, override data
}

Response:

{
  "id": "string",
  "created_at": "ISO 8601 datetime",
  "language": "string",
  "persistent": boolean,
  "file_count": number,
  "total_size_bytes": number,
  "source_session_id": "string"
}

Example:

curl -X POST https://anewera.dev/api/sessions/my-session/duplicate \
  -H "Content-Type: application/json" \
  -d '{
    "new_id": "my-session-backup"
  }'

---

PATCH /api/sessions/{id}

Update session configuration (timeout, network access, etc.).

Request Body:

{
  "default_timeout": 120,          // optional, default timeout in seconds
  "allowInternetAccess": false,    // optional, enable/disable outbound requests
  "allowPublicAccess": false       // optional, enable/disable inbound proxy requests
}

Response:

{
  "success": true,
  "id": "string",
  "metadata": {
    "default_timeout": 120,
    "allowInternetAccess": false,
    "allowPublicAccess": false,
    ...
  },
  "updated_at": "ISO 8601 datetime"
}

Example:

# Update default timeout to 5 minutes
curl -X PATCH https://anewera.dev/api/sessions/my-session \
  -H "Content-Type: application/json" \
  -d '{
    "default_timeout": 300
  }'

# Disable internet access
curl -X PATCH https://anewera.dev/api/sessions/my-session \
  -H "Content-Type: application/json" \
  -d '{
    "allowInternetAccess": false
  }'

# Update multiple fields at once
curl -X PATCH https://anewera.dev/api/sessions/my-session \
  -H "Content-Type: application/json" \
  -d '{
    "default_timeout": 600,
    "allowInternetAccess": true
  }'

→ See Timeout Configuration Guide for more details

---

GET /api/sessions/{id}/files

List all files in a session.

Response:

{
  "files": [
    {
      "path": "string",
      "size": number,
      "modified_at": "ISO 8601 datetime"
    }
  ],
  "total_count": number,
  "total_size_bytes": number
}

Example:

curl https://anewera.dev/api/sessions/my-session/files

---

GET /api/sessions/{id}/files/{path}

Download a specific file from a session.

Response: File contents (binary or text)

Example:

# Download a file
curl https://anewera.dev/api/sessions/my-session/files/data.json -o data.json

# View text file content
curl https://anewera.dev/api/sessions/my-session/files/output.txt

---

PUT /api/sessions/{id}/files/{path}

Upload a file to a session. File will be available on next code execution.

Request Body: File contents (binary or text)

Response:

{
  "path": "string",
  "size": number
}

Example:

# Upload JSON file
curl -X PUT https://anewera.dev/api/sessions/my-session/files/data.json \
  -H "Content-Type: application/json" \
  --data-binary @data.json

# Upload text file
echo "Hello World" | curl -X PUT https://anewera.dev/api/sessions/my-session/files/hello.txt \
  --data-binary @-

# Upload binary file
curl -X PUT https://anewera.dev/api/sessions/my-session/files/image.png \
  -H "Content-Type: image/png" \
  --data-binary @image.png

---

DELETE /api/sessions/{id}

Delete a session and all its data.

Response:

{
  "success": true,
  "id": "string",
  "deleted_at": "ISO 8601 datetime"
}

Example:

curl -X DELETE https://anewera.dev/api/sessions/my-session

---

DELETE /api/sessions

Delete all sessions and their data (bulk cleanup).

⚠️ Warning: This permanently deletes ALL sessions and their files. Use with caution!

Response:

{
  "success": true,
  "deleted_count": number,
  "deleted_sessions": ["string"],
  "deleted_at": "ISO 8601 datetime"
}

Example:

# Delete all sessions
curl -X DELETE https://anewera.dev/api/sessions

# Response
{
  "success": true,
  "deleted_count": 3,
  "deleted_sessions": ["session-1", "session-2", "session-3"],
  "deleted_at": "2025-01-15T10:30:00Z"
}

Use Cases:

• Development/testing cleanup
• Batch operations cleanup
• Server maintenance

⚠️ Timeout Limitation:

• Worker CPU time limits apply (30 seconds on paid plans)
• With 50+ sessions, the request may timeout
• If timeout occurs, simply retry - it will delete the remaining sessions
• For very large cleanups, call this endpoint multiple times

---

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "ISO 8601 datetime",
  "version": "string"
}

Example:

curl https://anewera.dev/health

Error Responses

All endpoints return standard error responses:

{
  "error": "string",
  "message": "string",
  "code": "ERROR_CODE"
}

Common HTTP Status Codes:

• 200 - Success
• 201 - Created (new session)
• 400 - Bad Request (invalid input)
• 404 - Not Found (session doesn’t exist)
• 408 - Request Timeout (execution timeout)
• 500 - Internal Server Error

Rate Limits

Currently no rate limits are enforced, but sessions are subject to:

• Execution timeout: 30 seconds (default, configurable)
• File storage: No hard limit (reasonable use)
• Session lifetime: Persistent until explicitly deleted

Language Runtimes

Python

• Version: Python 3.x
• Standard library available
• No network access
• File I/O to session directory

Node.js

• Version: Node.js 18+
• Core modules available
• No network access
• File I/O to session directory

TypeScript

• Automatic transpilation to JavaScript
• Runs on Node.js runtime
• All Node.js features available

Go

• Version: Go 1.21+
• Standard library available
• No network access
• File I/O to session directory

Deno

• Version: Deno 1.40+
• Native TypeScript and JavaScript support
• Standard library and Web APIs available
• Permissions: --allow-read --allow-write for file operations
• No network access
• File I/O to session directory

---

Storage Proxy API

Access KV, D1, and R2 storage from your sandboxed code. The SDK is automatically injected into every session.

GET /api/storage/kv/:namespace/:key

Get a value from KV storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Key to retrieve

Response:

{
  "value": "string"
}

Example:

curl https://anewera.dev/api/storage/kv/myapp/config

---

PUT /api/storage/kv/:namespace/:key

Set a value in KV storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Key to set

Request Body:

{
  "value": "string",
  "metadata": {
    "custom": "data"
  }
}

Response:

{
  "success": true
}

Example:

curl -X PUT https://anewera.dev/api/storage/kv/myapp/config \
  -H "Content-Type: application/json" \
  -d '{"value": "{\"theme\":\"dark\"}"}'

---

DELETE /api/storage/kv/:namespace/:key

Delete a key from KV storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Key to delete

Response:

{
  "success": true
}

---

GET /api/storage/kv/:namespace

List keys in a KV namespace.

Parameters:

• namespace (path) - Storage namespace
• prefix (query) - Optional key prefix filter
• limit (query) - Optional limit (default: 100)

Response:

{
  "keys": [
    {
      "name": "config",
      "metadata": {}
    }
  ],
  "list_complete": true,
  "cursor": "string"
}

Example:

curl "https://anewera.dev/api/storage/kv/myapp?prefix=user:&limit=50"

---

POST /api/storage/d1/:namespace/query

Execute a SELECT query on D1 database.

Parameters:

• namespace (path) - Database namespace

Request Body:

{
  "sql": "SELECT * FROM users WHERE id = ?",
  "params": [123]
}

Response:

{
  "success": true,
  "results": [
    {"id": 123, "name": "Alice"}
  ],
  "meta": {
    "duration": 12
  }
}

Example:

curl -X POST https://anewera.dev/api/storage/d1/myapp/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users", "params": []}'

---

POST /api/storage/d1/:namespace/exec

Execute a statement (INSERT, UPDATE, DELETE, CREATE TABLE, etc.) on D1 database.

Parameters:

• namespace (path) - Database namespace

Request Body:

{
  "sql": "INSERT INTO users (name) VALUES (?)",
  "params": ["Bob"]
}

Response:

{
  "success": true,
  "meta": {
    "duration": 8,
    "changes": 1
  }
}

---

GET /api/storage/r2/:namespace/:key

Get an object from R2 storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Object key

Response:

{
  "content": "base64_encoded_content",
  "size": 1024,
  "httpMetadata": {},
  "customMetadata": {}
}

---

PUT /api/storage/r2/:namespace/:key

Put an object in R2 storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Object key

Request Body:

{
  "content": "base64_encoded_content",
  "metadata": {
    "type": "image/jpeg"
  }
}

Response:

{
  "success": true,
  "size": 1024
}

---

DELETE /api/storage/r2/:namespace/:key

Delete an object from R2 storage.

Parameters:

• namespace (path) - Storage namespace
• key (path) - Object key

Response:

{
  "success": true
}

---

GET /api/storage/r2/:namespace

List objects in an R2 namespace.

Parameters:

• namespace (path) - Storage namespace
• prefix (query) - Optional key prefix filter
• limit (query) - Optional limit (default: 100)

Response:

{
  "objects": [
    {
      "key": "file.txt",
      "size": 1024,
      "uploaded": "2025-10-25T10:00:00Z"
    }
  ],
  "truncated": false,
  "cursor": "string"
}

---

Resource Registry API

Discover and manage all storage resources.

GET /api/resources/list

List all storage resources with optional filters.

Query Parameters:

• type (optional) - Filter by type: kv, d1, r2, do
• namespace (optional) - Filter by namespace
• key_prefix (optional) - Filter by key prefix
• limit (optional) - Results per page (default: 100)
• offset (optional) - Pagination offset (default: 0)

Response:

{
  "resources": [
    {
      "type": "kv",
      "namespace": "myapp",
      "key": "config",
      "created_at": "2025-10-25T10:00:00Z",
      "updated_at": "2025-10-25T11:00:00Z",
      "size": 45,
      "metadata": {}
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 100,
  "has_more": false
}

Example:

# List all resources
curl https://anewera.dev/api/resources/list

# Filter by namespace
curl "https://anewera.dev/api/resources/list?namespace=myapp"

# Filter by type
curl "https://anewera.dev/api/resources/list?type=kv"

---

GET /api/resources/stats

Get statistics about storage resource usage.

Response:

{
  "total": 42,
  "by_type": {
    "kv": 15,
    "d1": 3,
    "r2": 24,
    "do": 0
  },
  "by_namespace": {
    "myapp": 20,
    "cache": 15,
    "shared": 7
  },
  "total_size": 1048576
}

Example:

curl https://anewera.dev/api/resources/stats