Creating Resources

A resource is an API integration that connects external services to Mirra agents. This guide covers everything you need to create, configure, test, and publish resources on the Mirra Store.

By the end of this guide, you will understand how to define API endpoints using OpenAPI 3.0, configure authentication methods, set pricing models, and publish your resource to the marketplace.

What is a resource?

A resource is an API service or integration that users can install and use through their Mirra agents. Resources expose external APIs to the Mirra platform using the OpenAPI 3.0 specification format.

How resources work

When you create a resource, you define:

1. API endpoints - The URLs and HTTP methods your API supports
2. Authentication - How users authenticate with your API
3. Request/response schemas - The structure of data sent and received
4. Pricing - How you monetize access to your API

Users install your resource into their agents, provide authentication credentials (if required), and then their agents can call your API endpoints through natural language interactions.

Use cases for resources

Resources are ideal for:

• External APIs - Weather data, maps, geocoding, currency conversion
• Database connectors - PostgreSQL, MongoDB, Redis, Elasticsearch
• Payment gateways - Stripe, PayPal, Square payment processing
• AI services - OpenAI, Anthropic, Hugging Face model access
• Communication services - Twilio SMS, SendGrid email, Slack messaging
• Custom APIs - Your own services and microservices

Prerequisites

Before creating a resource, ensure you have:

• API to integrate - A working API with accessible endpoints
• OpenAPI 3.0 specification - API documentation in OpenAPI format (or ability to create it)
• Authentication details - Information about how users authenticate with your API
• Test credentials - API keys or tokens for testing your integration

Creating a resource

Follow these steps to create and publish a resource on the Mirra Store.

{
  "name": "Weather API",
  "description": "Real-time weather data and forecasts for any location worldwide",
  "category": "Data & APIs",
  "tags": ["weather", "forecast", "climate", "meteorology", "temperature"]
}

openapi: 3.0.0
info:
  title: Weather API
  version: 1.0.0
  description: Real-time weather data and forecasts
servers:
  - url: https://api.weather.example.com/v1
paths:
  /current:
    get:
      summary: Get current weather
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current weather data
          content:
            application/json:
              schema:
                type: object
                properties:
                  temperature:
                    type: number
                  conditions:
                    type: string

security: []

{
  "location": "San Francisco, CA"
}

{
  "temperature": 68,
  "conditions": "Partly Cloudy",
  "humidity": 65,
  "windSpeed": 12
}

OpenAPI specification best practices

Follow these best practices when creating your OpenAPI specification:

Clear endpoint descriptions

Provide clear, concise descriptions for all endpoints:

paths:
  /current:
    get:
      summary: Get current weather conditions
      description: Returns real-time weather data including temperature, conditions, humidity, and wind speed for the specified location.

Comprehensive parameter documentation

Document all parameters with descriptions, types, and examples:

parameters:
  - name: location
    in: query
    required: true
    description: City name, zip code, or coordinates (lat,lon)
    schema:
      type: string
    example: "San Francisco, CA"

Detailed response schemas

Define complete response schemas with property descriptions:

responses:
  '200':
    description: Successful response
    content:
      application/json:
        schema:
          type: object
          properties:
            temperature:
              type: number
              description: Temperature in Fahrenheit
            conditions:
              type: string
              description: Current weather conditions

Error handling

Document all possible error responses:

responses:
  '400':
    description: Invalid location parameter
  '401':
    description: Invalid or missing API key
  '429':
    description: Rate limit exceeded
  '500':
    description: Internal server error

Reusable components

Use components to avoid repetition:

components:
  schemas:
    WeatherData:
      type: object
      properties:
        temperature:
          type: number
        conditions:
          type: string
  responses:
    UnauthorizedError:
      description: Invalid or missing authentication

Authentication best practices

Follow these best practices when configuring authentication:

API key security

• Never expose your own API keys - Users provide their own keys
• Document key requirements - Explain how users get API keys
• Support key rotation - Allow users to update their keys
• Validate keys properly - Return clear error messages for invalid keys

OAuth2 configuration

• Request minimal scopes - Only request permissions you need
• Handle token refresh - Implement automatic token refresh
• Provide clear instructions - Explain the authorization process
• Test authorization flow - Verify the complete OAuth flow works

Credential storage

• Platform handles storage - Credentials are encrypted and stored securely
• Users control access - Users can revoke access at any time
• No credential exposure - Your code never sees raw credentials
• Automatic injection - Platform injects credentials into requests

Pricing strategies

Choose the right pricing strategy for your resource:

Free tier strategy

Start with a free tier to build your user base:

{
  "pricingModel": "free",
  "rateLimits": {
    "requestsPerDay": 1000,
    "requestsPerMinute": 10
  }
}

Benefits: User acquisition, feedback collection, market validation

Freemium model

Offer basic features free with paid upgrades:

• Free tier - Limited requests, basic features
• Pro tier - Higher limits, advanced features
• Enterprise tier - Unlimited requests, premium support

Usage-based pricing

Charge based on actual usage:

• Low volume - $0.001 per request (1000 requests = $1)
• Medium volume - $0.01 per request (100 requests = $1)
• High value - $0.10 per request (10 requests = $1)

Subscription pricing

Offer unlimited access for a fixed fee:

• Basic - $9.99/month - Standard features
• Pro - $29.99/month - Advanced features
• Enterprise - $99.99/month - All features + support

Troubleshooting

Common issues when creating resources and their solutions.

OpenAPI validation errors

Problem: Your OpenAPI specification fails validation.

Solutions:

• Use Swagger Editor to validate your spec
• Check that openapi version is 3.0.x (not 2.0)
• Ensure all required fields are present (info, paths, servers)
• Verify schema references are correct ($ref paths)
• Check for syntax errors in YAML or JSON

Authentication not working

Problem: API requests fail with authentication errors.

Solutions:

• Verify security scheme is correctly defined in components.securitySchemes
• Check that security requirement is applied to endpoints
• Test with valid credentials in the testing panel
• Ensure API key location (header/query/cookie) matches your API
• For OAuth2, verify authorization and token URLs are correct

Endpoints not appearing

Problem: Some endpoints don't appear in the generated documentation.

Solutions:

• Check that endpoints are defined under paths in your spec
• Ensure each endpoint has at least one HTTP method (get, post, etc.)
• Verify YAML/JSON syntax is correct (indentation, commas)
• Check for duplicate path definitions
• Ensure all required fields are present for each operation

Rate limiting issues

Problem: Users hit rate limits too quickly.

Solutions:

• Implement rate limiting in your API
• Document rate limits in your resource description
• Consider higher limits for paid tiers
• Provide clear error messages when limits are exceeded
• Allow users to monitor their usage

Next steps

Now that you understand how to create resources, explore these related topics:

• Creating Scripts - Build automation scripts that use your resources
• Managing Your Profile - Optimize your developer profile
• Handling Reviews - Engage with users and respond to feedback
• Best Practices - Tips for building successful integrations

See also

• Core Concepts: Resources - Understanding resources in depth
• Examples: Resources - Working resource examples with complete code
• Getting Started: Authentication - Authentication patterns and best practices
• OpenAPI 3.0 Specification - Official OpenAPI documentation
• Swagger Editor - Online OpenAPI editor and validator