{
  "openapi": "3.0.3",
  "info": {
    "title": "InstantAPI",
    "description": "AI-powered utility API offering 6 tasks: summarize, extract, analyze, translate, sentiment, and code. All through a single endpoint at $0.50 per call.",
    "version": "1.0.0",
    "contact": {
      "name": "InstantAPI Support",
      "email": "support@instantapis.net",
      "url": "https://instantapis.net"
    },
    "termsOfService": "https://instantapis.net/terms"
  },
  "servers": [
    {
      "url": "https://instantapis.net",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/generate": {
      "post": {
        "summary": "Process a single AI task",
        "description": "Send text to one of 6 AI tasks and receive structured results. Costs 1 credit ($0.50) per call.",
        "operationId": "generate",
        "tags": ["Generate"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              },
              "examples": {
                "summarize": {
                  "summary": "Summarize text",
                  "value": {
                    "task": "summarize",
                    "input": "Artificial intelligence has transformed the way businesses operate...",
                    "options": { "length": "short" }
                  }
                },
                "extract": {
                  "summary": "Extract structured data",
                  "value": {
                    "task": "extract",
                    "input": "Contact John Smith at john@example.com or call (555) 123-4567.",
                    "options": { "fields": ["name", "email", "phone"] }
                  }
                },
                "sentiment": {
                  "summary": "Analyze sentiment",
                  "value": {
                    "task": "sentiment",
                    "input": "I absolutely love this product! Best purchase I've made all year."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "Maximum requests per window"
              },
              "X-RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "Remaining requests in current window"
              },
              "X-RateLimit-Reset": {
                "schema": { "type": "integer" },
                "description": "Unix timestamp when the rate limit resets"
              }
            }
          },
          "400": {
            "description": "Invalid request (bad task type, missing input, invalid JSON)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "402": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": { "type": "integer" },
                "description": "Seconds until rate limit resets"
              }
            }
          },
          "500": {
            "description": "Internal server error (AI processing failed)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/batch": {
      "post": {
        "summary": "Process multiple AI tasks in one request",
        "description": "Send up to 20 tasks in a single request. Tasks are processed concurrently (max 5 parallel). Credits are deducted upfront and refunded for failed tasks.",
        "operationId": "batch",
        "tags": ["Batch"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              },
              "example": {
                "tasks": [
                  { "id": "req_1", "task": "summarize", "input": "Long article text..." },
                  { "id": "req_2", "task": "sentiment", "input": "I love this product!" },
                  { "id": "req_3", "task": "extract", "input": "John at john@example.com", "options": { "fields": ["name", "email"] } }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch completed (may include partial failures)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "402": {
            "description": "Insufficient credits for all tasks",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Get batch endpoint info",
        "description": "Returns information about the batch endpoint including supported tasks and limits.",
        "operationId": "batchInfo",
        "tags": ["Batch"],
        "security": [],
        "responses": {
          "200": {
            "description": "Batch endpoint information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key starting with `ia_live_`. Get yours at https://instantapis.net/login"
      }
    },
    "schemas": {
      "GenerateRequest": {
        "type": "object",
        "required": ["task", "input"],
        "properties": {
          "task": {
            "type": "string",
            "enum": ["summarize", "extract", "analyze", "translate", "sentiment", "code"],
            "description": "The AI task to perform"
          },
          "input": {
            "type": "string",
            "description": "The text to process",
            "minLength": 1
          },
          "options": {
            "type": "object",
            "description": "Task-specific options",
            "properties": {
              "length": {
                "type": "string",
                "enum": ["short", "medium", "long"],
                "description": "Summary length (summarize task only)"
              },
              "fields": {
                "type": "array",
                "items": { "type": "string" },
                "description": "Fields to extract (extract task only)"
              },
              "targetLanguage": {
                "type": "string",
                "description": "Target language code or name (translate task only)"
              },
              "language": {
                "type": "string",
                "description": "Target programming language (code task only)"
              }
            }
          }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "description": "Task-specific result data"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": ["tasks"],
        "properties": {
          "tasks": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/BatchTask"
            }
          }
        }
      },
      "BatchTask": {
        "type": "object",
        "required": ["task", "input"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Optional client-provided ID for correlation. Auto-generated if omitted."
          },
          "task": {
            "type": "string",
            "enum": ["summarize", "extract", "analyze", "translate", "sentiment", "code"]
          },
          "input": {
            "type": "string",
            "minLength": 1
          },
          "options": {
            "type": "object"
          }
        }
      },
      "BatchResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/BatchResult"
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "total": { "type": "integer" },
                  "succeeded": { "type": "integer" },
                  "failed": { "type": "integer" }
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "requestId": { "type": "string" },
              "credits_remaining": { "type": "integer" },
              "totalLatencyMs": { "type": "integer" }
            }
          }
        }
      },
      "BatchResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "success": { "type": "boolean" },
          "data": { "type": "object", "nullable": true },
          "error": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "data": {
            "type": "object",
            "nullable": true,
            "example": null
          },
          "error": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique request identifier for debugging"
          },
          "credits_remaining": {
            "type": "integer",
            "description": "Credits remaining after this request"
          }
        }
      }
    }
  }
}