Resources

Resources are installable API endpoints, LLM integrations, and third-party service connections that scripts and templates can invoke. Resources provide standardized access to external services through OpenAPI 3.0 specifications, enabling type-safe integration with authentication, rate limiting, and usage tracking.

Syntax

Creating a Resource

POST /api/sdk/v1/resources

Resource Structure

{
  "name": "Resource Name",
  "description": "Resource description",
  "resourceType": "api | llm | script | integration",
  "openApiSpec": { /* OpenAPI 3.0 specification */ },
  "endpoint": { /* Endpoint configuration */ },
  "pricing": { /* Pricing model */ }
}

Resource Types

Mirra supports four resource types, each optimized for specific integration patterns.

API

api

Standard HTTP APIs with defined methods, authentication, and request/response schemas. API resources expose RESTful endpoints for data retrieval, manipulation, and service integration.

{
  "resourceType": "api",
  "endpoint": {
    "baseUrl": "https://api.example.com",
    "authentication": "api_key",
    "methods": [
      {
        "name": "getData",
        "httpMethod": "GET",
        "path": "/v1/data"
      }
    ]
  }
}

LLM

llm

Large Language Model endpoints for chat completion, text generation, and AI-powered processing. LLM resources provide standardized access to language models with token counting and cost tracking.

{
  "resourceType": "llm",
  "endpoint": {
    "baseUrl": "https://api.openai.com/v1",
    "authentication": "bearer",
    "methods": [
      {
        "name": "chatCompletion",
        "httpMethod": "POST",
        "path": "/chat/completions"
      }
    ]
  }
}

LLM resources are treated as standard API endpoints. To create a chat UI with subdomain deployment, bundle your LLM resource in a Template.

Script

script

Serverless functions deployed to the Mirra platform that can be invoked as resources. Script resources enable custom logic and data processing within the Mirra ecosystem.

{
  "resourceType": "script",
  "endpoint": {
    "baseUrl": "https://api.getmirra.app/scripts/your-function",
    "authentication": "none"
  }
}

Integration

integration

Third-party service integrations with OAuth 2.0 or complex authentication flows. Integration resources handle token management, refresh logic, and service-specific authentication patterns.

{
  "resourceType": "integration",
  "endpoint": {
    "baseUrl": "https://api.service.com",
    "authentication": "oauth2",
    "authConfig": {
      "authUrl": "https://oauth.service.com/authorize",
      "tokenUrl": "https://oauth.service.com/token",
      "scopes": ["read", "write"]
    }
  }
}

Description

Resources provide the foundation for external service integration within Mirra. Each resource encapsulates an API endpoint, authentication mechanism, and method definitions in a standardized format that Scripts and Templates can invoke.

All resources require a valid OpenAPI 3.0 specification, which the platform uses for automatic documentation generation, request/response validation, and SDK client generation. This specification-driven approach ensures type safety and clear contracts between resource providers and consumers.

OpenAPI Specification

Resources must include a complete OpenAPI 3.0 specification defining all endpoints, parameters, request bodies, and response schemas. The platform validates incoming requests against this specification and generates interactive documentation for resource consumers.

A minimal OpenAPI specification includes:

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "API description"
  },
  "servers": [
    {
      "url": "https://api.example.com"
    }
  ],
  "paths": {
    "/endpoint": {
      "get": {
        "summary": "Get data",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

The OpenAPI specification provides four critical capabilities:

Auto-generated documentation - Interactive API documentation for resource consumers
Type safety - Request and response validation against defined schemas
SDK generation - Automatic client library generation for multiple languages
Clear contracts - Explicit interface definitions between providers and consumers

Authentication Methods

Resources support five authentication mechanisms, each configured through the authentication field and optional authConfig object.

none

No authentication required. Use for public APIs or resources with custom authentication logic.

{
  "authentication": "none"
}

api_key

API key authentication via header or query parameter. Specify the header name and location in authConfig.

{
  "authentication": "api_key",
  "authConfig": {
    "headerName": "X-API-Key",
    "location": "header"
  }
}

bearer

Bearer token authentication using the Authorization header. Commonly used for JWT tokens and OAuth 2.0 access tokens.

{
  "authentication": "bearer",
  "authConfig": {
    "tokenField": "access_token"
  }
}

basic

HTTP Basic authentication with username and password. Credentials are base64-encoded in the Authorization header.

{
  "authentication": "basic",
  "authConfig": {
    "usernameField": "username",
    "passwordField": "password"
  }
}

oauth2

OAuth 2.0 authentication flow with authorization URL, token URL, and scopes. The platform handles token refresh and expiration.

{
  "authentication": "oauth2",
  "authConfig": {
    "authUrl": "https://oauth.example.com/authorize",
    "tokenUrl": "https://oauth.example.com/token",
    "scopes": ["read", "write"]
  }
}

Method Definitions

Each resource method defines an HTTP operation with parameters, request body schema, response schema, and optional cost tracking.

{
  "name": "createUser",
  "httpMethod": "POST",
  "path": "/v1/users",
  "description": "Create a new user account",
  "parameters": {
    "email": {
      "type": "string",
      "required": true,
      "description": "User email address"
    },
    "name": {
      "type": "string",
      "required": false,
      "description": "User full name",
      "default": "Anonymous"
    }
  },
  "response": {
    "type": "object",
    "schema": {
      "id": "string",
      "email": "string",
      "createdAt": "string"
    }
  },
  "cost": 0.01
}

Method definitions support all standard HTTP methods (GET, POST, PUT, PATCH, DELETE) and include path parameters using curly brace syntax: /users/{userId}.

Rate Limiting

Resources can define rate limits to control usage and prevent abuse. Rate limits specify the maximum number of requests allowed within a time window.

{
  "rateLimit": {
    "requests": 1000,
    "window": "1h"
  }
}

Supported time windows:

1m - One minute
1h - One hour
1d - One day

When a rate limit is exceeded, the platform returns a 429 Too Many Requests response with a Retry-After header indicating when the next request can be made.

Examples

Creating an API Resource

This example creates a cryptocurrency price API resource with API key authentication and pay-per-call pricing.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/resources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Crypto Price API",
    "description": "Real-time cryptocurrency prices",
    "resourceType": "api",
    "category": "crypto",
    "tags": ["crypto", "prices", "trading"],
    "openApiSpec": {
      "openapi": "3.0.0",
      "info": {
        "title": "Crypto Price API",
        "version": "1.0.0"
      },
      "servers": [{"url": "https://api.crypto-prices.com"}],
      "paths": {
        "/v1/price/{symbol}": {
          "get": {
            "summary": "Get cryptocurrency price",
            "parameters": [
              {
                "name": "symbol",
                "in": "path",
                "required": true,
                "schema": {"type": "string"}
              }
            ],
            "responses": {
              "200": {
                "description": "Price data",
                "content": {
                  "application/json": {
                    "schema": {
                      "type": "object",
                      "properties": {
                        "price": {"type": "number"},
                        "symbol": {"type": "string"}
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "endpoint": {
      "baseUrl": "https://api.crypto-prices.com",
      "authentication": "api_key",
      "methods": [
        {
          "name": "getPrice",
          "httpMethod": "GET",
          "path": "/v1/price/{symbol}",
          "description": "Get current price for a cryptocurrency",
          "parameters": {
            "symbol": {
              "type": "string",
              "required": true
            }
          },
          "response": {
            "type": "object"
          }
        }
      ]
    },
    "pricing": {
      "model": "pay-per-call",
      "basePrice": 0.001,
      "currency": "USDC"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "resource_abc123",
    "name": "Crypto Price API",
    "resourceType": "api",
    "status": "draft",
    "createdAt": "2025-11-15T12:00:00Z"
  }
}

The resource is created in draft status and must be published before it appears in the marketplace.

Creating an LLM Resource

This example creates an OpenAI GPT-4 resource with bearer token authentication for chat completion.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/resources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPT-4 Chat",
    "description": "OpenAI GPT-4 chat completion endpoint",
    "resourceType": "llm",
    "category": "ai",
    "tags": ["llm", "chat", "openai"],
    "openApiSpec": {
      "openapi": "3.0.0",
      "info": {
        "title": "OpenAI Chat API",
        "version": "1.0.0"
      },
      "servers": [{"url": "https://api.openai.com/v1"}],
      "paths": {
        "/chat/completions": {
          "post": {
            "summary": "Create chat completion",
            "requestBody": {
              "required": true,
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "model": {"type": "string"},
                      "messages": {"type": "array"}
                    }
                  }
                }
              }
            },
            "responses": {
              "200": {
                "description": "Chat completion response"
              }
            }
          }
        }
      }
    },
    "endpoint": {
      "baseUrl": "https://api.openai.com/v1",
      "authentication": "bearer",
      "methods": [
        {
          "name": "chatCompletion",
          "httpMethod": "POST",
          "path": "/chat/completions",
          "description": "Generate chat completion",
          "parameters": {
            "model": {"type": "string", "required": true},
            "messages": {"type": "array", "required": true}
          },
          "response": {"type": "object"},
          "cost": 0.002
        }
      ]
    },
    "pricing": {
      "model": "pay-per-call",
      "basePrice": 0.002,
      "currency": "USDC"
    }
  }'

To create a chat UI with subdomain deployment (e.g., mychat.username.getmirra.app), bundle your LLM resource in a Template.

Installing a Resource

Users install resources to their account before invoking methods. Installation creates an installation record and prepares the resource for authentication.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/resources/RESOURCE_ID/install \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "installationId": "inst_789",
    "resourceId": "resource_123",
    "userId": "user_456",
    "isAuthenticated": false,
    "status": "active",
    "installedAt": "2025-11-05T12:00:00Z"
  }
}

The isAuthenticated field indicates whether the user has provided credentials. Resources requiring authentication must be authenticated before use.

Authenticating a Resource

After installation, users provide credentials for resources requiring authentication. The platform securely stores credentials and injects them into API requests.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/resources/RESOURCE_ID/authenticate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "api_key",
    "credentials": {
      "apiKey": "sk_live_..."
    }
  }'

Credential Formats

API Key

{
  "type": "api_key",
  "credentials": {
    "apiKey": "sk_live_..."
  }
}

OAuth 2.0

{
  "type": "oauth2",
  "credentials": {
    "accessToken": "ya29.a0...",
    "refreshToken": "1//0g...",
    "expiresAt": "2025-11-05T13:00:00Z"
  }
}

Basic Auth

{
  "type": "basic",
  "credentials": {
    "username": "user@example.com",
    "password": "password123"
  }
}

Tracking Usage Metrics

Resource consumers can track their usage and costs per installation. The usage endpoint returns call counts, costs, and recent activity.

Request

curl https://api.fxn.world/api/sdk/v1/resources/installations/INSTALLATION_ID/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "totalCalls": 547,
    "totalCost": 0.547,
    "callsToday": 23,
    "lastUsedAt": "2025-11-05T11:45:00Z",
    "recentCalls": [
      {
        "timestamp": "2025-11-05T11:45:00Z",
        "method": "getPrice",
        "cost": 0.001,
        "duration": 234,
        "success": true
      }
    ]
  }
}

Viewing Resource Metrics

Resource creators can view aggregated metrics across all users, including total users, calls, revenue, and ratings.

Request

curl https://api.fxn.world/api/sdk/v1/resources/RESOURCE_ID/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "totalUsers": 156,
    "totalCalls": 45678,
    "totalRevenue": 45.678,
    "rating": 4.7,
    "reviewCount": 34
  }
}

Publishing to Marketplace

Resources must be published to appear in the marketplace and become available for installation. Publishing validates the resource configuration and makes it discoverable.

Request

curl -X POST https://api.fxn.world/api/sdk/v1/resources/RESOURCE_ID/publish \
  -H "Authorization: Bearer YOUR_API_KEY"

Publishing Requirements

Valid name and description
At least one method defined
Valid OpenAPI 3.0 specification
All method schemas validated

To unpublish a resource and remove it from the marketplace:

curl -X POST https://api.fxn.world/api/sdk/v1/resources/RESOURCE_ID/unpublish \
  -H "Authorization: Bearer YOUR_API_KEY"

Unpublishing prevents new installations but does not affect existing installations.

Pricing Models

Resources support four pricing models to monetize API access and service usage.

Free

free

No cost for resource usage. Suitable for open APIs, promotional resources, or community-contributed integrations.

{
  "pricing": {
    "model": "free"
  }
}

Pay-Per-Call

pay-per-call

Charges a fixed price per method invocation. Users pay only for actual usage with no recurring fees.

{
  "pricing": {
    "model": "pay-per-call",
    "basePrice": 0.001,
    "currency": "USDC"
  }
}

Subscription

subscription

Charges a recurring monthly fee for unlimited access. Suitable for high-volume use cases with predictable costs.

{
  "pricing": {
    "model": "subscription",
    "basePrice": 10.0,
    "currency": "USDC"
  }
}

Tiered

tiered

Offers multiple subscription tiers with included call quotas and overage pricing. Provides flexibility for different usage levels.

{
  "pricing": {
    "model": "tiered",
    "subscriptionTiers": [
      {
        "name": "Basic",
        "price": 10.0,
        "includedCalls": 1000,
        "overagePrice": 0.01
      },
      {
        "name": "Pro",
        "price": 50.0,
        "includedCalls": 10000,
        "overagePrice": 0.005
      }
    ]
  }
}

Troubleshooting

Authentication Failures

When resource authentication fails, verify the following:

Credentials match the format expected by the authentication type
Authentication type in credentials matches the resource configuration
OAuth 2.0 tokens have not expired (check expiresAt field)
API keys have the necessary permissions for the requested operations
Bearer tokens are valid and not revoked

For OAuth 2.0 resources, the platform automatically refreshes expired tokens using the refresh token. If refresh fails, re-authenticate the resource with new credentials.

Rate Limit Errors

When encountering 429 Too Many Requests responses:

Implement exponential backoff and retry logic in your scripts
Check the Retry-After header for the next available request time
Consider upgrading to a higher pricing tier with increased limits
Batch multiple operations into single requests where possible
Cache frequently accessed data to reduce API calls

Method Not Found Errors

When a method cannot be invoked:

Verify the method name matches the resource definition exactly
Confirm the resource is published and available in the marketplace
Check that the user has installed and authenticated the resource
Ensure the method is included in the resource's OpenAPI specification
Verify the user's subscription tier includes access to the method

Invalid OpenAPI Specification

When resource creation fails due to specification errors:

Validate the OpenAPI specification using an online validator
Ensure all required fields (openapi, info, paths) are present
Verify response schemas include content and schema definitions
Check that parameter types match OpenAPI 3.0 data types
Confirm all $ref references resolve to defined components

Resources

On this page