{
  "openapi": "3.1.0",
  "info": {
    "title": "ActAs inbox API",
    "version": "0.1.0",
    "description": "Partial API reference for scoped email resources. ActAs also provides agent identities, encrypted credentials and account connections; see /docs for the customer workflow. External registration requires a browser runtime and verified outcome."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "security": [
    {
      "scopedBearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "scopedBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Explicit owner/product/action/resource/identity-field scope. Issued by authenticated human."
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "summary": "Read authorised identity and owner/product context",
        "responses": {
          "200": {
            "description": "Success; JSON data envelope"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          },
          "404": {
            "description": "Resource not available"
          },
          "503": {
            "description": "Required provider/configuration blocked"
          }
        }
      }
    },
    "/resources": {
      "get": {
        "summary": "List permitted email metadata; select provider=agentmail for live inboxes",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "emails"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permitted email resources"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          }
        }
      }
    },
    "/emails": {
      "post": {
        "summary": "Provision real email idempotently",
        "responses": {
          "200": {
            "description": "Success; JSON data envelope"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          },
          "404": {
            "description": "Resource not available"
          },
          "503": {
            "description": "Required provider/configuration blocked"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "/emails/{id}/messages": {
      "get": {
        "summary": "Read permitted messages",
        "responses": {
          "200": {
            "description": "Success; JSON data envelope"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          },
          "404": {
            "description": "Resource not available"
          },
          "503": {
            "description": "Required provider/configuration blocked"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/emails/{id}/messages/{messageId}": {
      "get": {
        "summary": "Read one permitted message",
        "responses": {
          "200": {
            "description": "Success; JSON data envelope"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          },
          "404": {
            "description": "Resource not available"
          },
          "503": {
            "description": "Required provider/configuration blocked"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/capabilities": {
      "get": {
        "summary": "Read configured and blocked provider capabilities",
        "responses": {
          "200": {
            "description": "Success; JSON data envelope"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Scope denied"
          },
          "404": {
            "description": "Resource not available"
          },
          "503": {
            "description": "Required provider/configuration blocked"
          }
        }
      }
    },
    "/handoffs": {
      "get": {
        "summary": "List handoff records",
        "description": "Requires handoffs:read; identity connections see their own records only.",
        "parameters": [
          {
            "name": "ownerId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "prepared",
                "human_done",
                "agent_took_over",
                "cancelled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Owner-scoped handoff records"
          }
        }
      },
      "post": {
        "summary": "Prepare a human-step handoff",
        "description": "Requires handoffs:write. Body: ownerId, service, HTTPS url, account, humanStep, steps (1\u20133 strings, max 200 characters each), requestedBy {agent, task?}; optional passwordPath, codeInbox {id,address}, prefill (non-secret string map). Vault/inbox references are checked without reading values.",
        "responses": {
          "201": {
            "description": "Prepared record with id and actasHandoffId"
          },
          "422": {
            "description": "Invalid reference, shape, or secret-looking text"
          }
        }
      }
    },
    "/handoffs/{id}": {
      "get": {
        "summary": "Read a handoff",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Handoff record"
          }
        }
      }
    },
    "/handoffs/{id}/human-done": {
      "post": {
        "summary": "Record that the human completed their step",
        "description": "Requires handoffs:write. One-way, idempotent transition; repeated transition adds no activity event. Body {note?}.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current handoff record"
          },
          "409": {
            "description": "Invalid state transition"
          }
        }
      }
    },
    "/handoffs/{id}/took-over": {
      "post": {
        "summary": "Record that the requesting agent took over",
        "description": "Requires handoffs:write. One-way, idempotent transition; repeated transition adds no activity event. Body {note?}.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current handoff record"
          },
          "409": {
            "description": "Invalid state transition"
          }
        }
      }
    },
    "/handoffs/{id}/cancel": {
      "post": {
        "summary": "Cancel an open handoff",
        "description": "Requires handoffs:write. One-way, idempotent transition; repeated transition adds no activity event. Body {note}.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current handoff record"
          },
          "409": {
            "description": "Invalid state transition"
          }
        }
      }
    }
  }
}