{
  "openapi": "3.1.0",
  "info": {
    "title": "Jorjar automation API",
    "version": "1.0.0",
    "description": "Owner-delegated assistant tasks. Create an expiring token in Your workspace → Automation tokens. Each token has one conversation and can read only its own tasks. Existing assistant authority checks apply; accepted work can continue after revocation."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "automationToken": []
    }
  ],
  "paths": {
    "/api/v1/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "Submit or retry an authorized task",
        "description": "Same id and prompt are idempotent. Account-wide quotas: 120 requests/minute, 10 new tasks/minute, 500 new tasks/day. Bodies max 65536 bytes. Follow-up tasks share the token conversation; submit them sequentially.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^[0-9a-f-]{36}$"
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 16000
                  }
                },
                "additionalProperties": false,
                "required": [
                  "id",
                  "prompt"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted, not necessarily finished",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^[0-9a-f-]{36}$"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within this token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting request ID or active task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Expected JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account limit reached; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Delay in seconds"
              }
            }
          },
          "502": {
            "description": "Upstream failure; retry same ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}": {
      "get": {
        "operationId": "getTask",
        "summary": "Read this token’s task",
        "description": "Poll queued/running/waiting with Retry-After. Terminal statuses: succeeded, failed, cancelled, steered. Read answer for any human step still required.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f-]{36}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task status and result",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^[0-9a-f-]{36}$"
                    },
                    "status": {
                      "type": "string"
                    },
                    "answer": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "progress": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "files": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "created_at": {
                      "type": "string"
                    },
                    "finished_at": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within this token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting request ID or active task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Expected JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account limit reached; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Delay in seconds"
              }
            }
          },
          "502": {
            "description": "Upstream failure; retry same ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tasks/{id}/files/{index}": {
      "get": {
        "operationId": "getTaskFile",
        "summary": "Download this token’s result file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f-]{36}$"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 99
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File with base64 data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "data": {
                      "type": "string",
                      "contentEncoding": "base64"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within this token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting request ID or active task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Expected JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account limit reached; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Delay in seconds"
              }
            }
          },
          "502": {
            "description": "Upstream failure; retry same ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/assistant/avatar": {
      "get": {
        "operationId": "getAssistantAvatar",
        "summary": "Read the assistant's own profile picture",
        "responses": {
          "200": {
            "description": "The current picture with base64 data; version changes whenever the picture does",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "image/png",
                        "image/jpeg",
                        "image/gif",
                        "image/webp"
                      ]
                    },
                    "version": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{16}$"
                    },
                    "data": {
                      "type": "string",
                      "contentEncoding": "base64"
                    }
                  },
                  "required": [
                    "type",
                    "version",
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The assistant has no profile picture yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account limit reached; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Delay in seconds"
              }
            }
          },
          "502": {
            "description": "Upstream failure; retry same ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setAssistantAvatar",
        "summary": "Change the assistant's own profile picture everywhere",
        "description": "One picture is used in every channel: Jorjar's web chat, Slack replies and emails show it at once; the owner's Telegram bot photo follows in the background. PNG, JPEG, GIF or WebP, at most 1 MiB (detected from the bytes). Setting the same picture again is a no-op with the same version. Use a square picture of at least 512×512 pixels: Telegram refuses very small ones (the other channels still update).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "The picture file, base64-encoded"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Picture kept and applied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{16}$"
                    }
                  },
                  "required": [
                    "version"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Picture larger than 1 MiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Expected JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Not a PNG, JPEG, GIF or WebP picture",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account limit reached; honor Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Delay in seconds"
              }
            }
          },
          "502": {
            "description": "Upstream failure; retry same ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/handovers": {
      "get": {
        "summary": "List steps waiting on the owner",
        "description": "Sign-ins Jorjar could not finish by itself (MFA, captcha, a hand-off to another sign-in provider) and assistant tasks paused for the owner. The same state the vault and the take-over view show. Take-over links are never returned: they are credentials for the owner's session in Jorjar's browser.",
        "responses": {
          "200": {
            "description": "Waiting steps",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "handovers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "managed-browser (an assistant task) or a saved website's id"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "task",
                              "website"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "site": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "username": {
                            "type": "string"
                          },
                          "credential_id": {
                            "type": "string",
                            "description": "The vault entry this sign-in uses, when known."
                          },
                          "needs_you": {
                            "type": "object",
                            "properties": {
                              "reason": {
                                "type": "string",
                                "enum": [
                                  "handoff",
                                  "verification",
                                  "form",
                                  "manual"
                                ]
                              },
                              "headline": {
                                "type": "string",
                                "description": "Always \"Needs you: continue in your browser.\""
                              },
                              "message": {
                                "type": "string",
                                "description": "The step, e.g. \"Imperial sends you to Microsoft sign-in.\""
                              },
                              "provider": {
                                "type": "string",
                                "description": "Sign-in service a hand-off went to, e.g. Microsoft."
                              },
                              "provider_host": {
                                "type": "string"
                              },
                              "control": {
                                "type": "string",
                                "enum": [
                                  "waiting",
                                  "watching",
                                  "controlling"
                                ],
                                "description": "waiting: nobody has the take-over view open; watching: view-only; controlling: the owner holds control and Jorjar's automation of that browser is paused."
                              }
                            },
                            "required": [
                              "reason",
                              "headline",
                              "message",
                              "control"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "kind",
                          "name",
                          "needs_you"
                        ]
                      }
                    }
                  },
                  "required": [
                    "handovers"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/handovers/{id}/done": {
      "post": {
        "summary": "Hand a step back (I'm done)",
        "description": "Jorjar checks the page, records the outcome and resumes the paused task. Refused with 409 while the owner holds control in the take-over view.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(managed-browser|[0-9a-f-]{36})$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Handed back",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "signed_in",
                        "changed",
                        "unchanged",
                        "unknown"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Nothing waits there"
          },
          "409": {
            "description": "The owner holds control"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "automationToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Owner-issued expiring automation token. Never send it in URLs."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
