{
  "openapi": "3.1.0",
  "info": {
    "title": "Needo personal-agent reads",
    "version": "1.0.0",
    "description": "Read-only, restaurant-scoped access. Complete verified Needo sign-up/sign-in and approve one restaurant before token access. Device sign-in is documented in api.md. Tokens are resource-bound; use the origin corresponding to the granted resource."
  },
  "servers": [
    {
      "url": "https://needo.co"
    },
    {
      "url": "https://drive.needo.co"
    },
    {
      "url": "https://invoice.needo.co"
    }
  ],
  "paths": {
    "/api/agent/v1/me": {
      "get": {
        "operationId": "getAccount",
        "summary": "Connected restaurant and permissions",
        "security": [
          {
            "NeedoOAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/drive/items": {
      "get": {
        "operationId": "listDriveItems",
        "summary": "List files and folders",
        "security": [
          {
            "NeedoOAuth": [
              "drive.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "parent",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/drive/search": {
      "get": {
        "operationId": "searchDrive",
        "summary": "Search file and folder names",
        "security": [
          {
            "NeedoOAuth": [
              "drive.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/drive/files/{id}": {
      "get": {
        "operationId": "downloadFile",
        "summary": "Download original document",
        "security": [
          {
            "NeedoOAuth": [
              "drive.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/invoices": {
      "get": {
        "operationId": "listInvoices",
        "summary": "Browse supplier invoices",
        "security": [
          {
            "NeedoOAuth": [
              "invoices.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "processing",
                "review",
                "reviewed",
                "failed",
                "duplicate",
                "ignored"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/invoices/{id}": {
      "get": {
        "operationId": "getInvoice",
        "summary": "Read invoice with line items and payments",
        "security": [
          {
            "NeedoOAuth": [
              "invoices.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    },
    "/api/agent/v1/invoices/{id}/source": {
      "get": {
        "operationId": "downloadInvoiceOriginal",
        "summary": "Download invoice original",
        "security": [
          {
            "NeedoOAuth": [
              "invoices.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated restaurant-scoped result"
          },
          "401": {
            "description": "Connect or sign in again"
          },
          "403": {
            "description": "Scope or access denied"
          },
          "404": {
            "description": "Record not found in the authorised restaurant"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "NeedoOAuth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://needo.co/oauth/authorize",
            "tokenUrl": "https://needo.co/oauth/token",
            "refreshUrl": "https://needo.co/oauth/token",
            "scopes": {
              "drive.read": "Browse and download restaurant documents",
              "invoices.read": "Browse supplier invoices, items and payment records"
            }
          }
        }
      }
    }
  }
}