{
  "openapi": "3.1.0",
  "info": {
    "title": "Riddle Actions API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.riddledc.com"
    }
  ],
  "paths": {
    "/v1/run/actions": {
      "post": {
        "operationId": "runActions",
        "summary": "Run a browser job (Actions-safe)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunActionsRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunActionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunActionsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunActionsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "operationId": "getJob",
        "summary": "Get job status",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/jobs/{job_id}/artifacts": {
      "get": {
        "operationId": "getJobArtifacts",
        "summary": "Get job artifacts manifest",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["actions"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artifacts manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtifactsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "RunActionsRequest": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "url": {
            "type": "string"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "script": {
            "type": "string"
          },
          "include": {
            "type": "array",
            "description": "Artifacts to inline in the response. By default, only URLs are returned. Specify which artifacts to fetch and include directly in the response payload.",
            "items": {
              "type": "string",
              "enum": ["final_screenshot", "screenshots", "console", "har", "html"]
            }
          },
          "sync": {
            "type": "boolean",
            "description": "Whether to wait for job completion and return results inline (default true). Set to false for async mode where you get a job_id and must poll for status.",
            "default": true
          },
          "timeout_sec": {
            "type": "integer"
          },
          "options": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Artifacts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "final_screenshot_url": {
            "type": "string",
            "nullable": true
          },
          "screenshots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArtifactEntry"
            }
          },
          "console_url": {
            "type": "string",
            "nullable": true
          },
          "har_url": {
            "type": "string",
            "nullable": true
          },
          "html_url": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ArtifactEntry": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "bytes": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "Limits": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "retention_seconds": {
            "type": "integer"
          },
          "expires_at": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "nullable": true
          }
        }
      },
      "RunActionsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "artifacts": {
            "$ref": "#/components/schemas/Artifacts"
          },
          "limits": {
            "$ref": "#/components/schemas/Limits"
          },
          "error": {
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/Error"
              },
              {
                "type": "null"
              }
            ]
          },
          "status_url": {
            "type": "string"
          },
          "artifacts_url": {
            "type": "string"
          }
        }
      },
      "JobStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "created_at": {
            "type": "string",
            "nullable": true
          },
          "duration_ms": {
            "type": "integer",
            "nullable": true
          },
          "error": {
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/Error"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "ArtifactsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          },
          "artifacts": {
            "$ref": "#/components/schemas/Artifacts"
          },
          "limits": {
            "$ref": "#/components/schemas/Limits"
          },
          "error": {
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/Error"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    }
  }
}