{
  "openapi": "3.1.0",
  "info": {
    "title": "Sachfolio API",
    "version": "sachfolio.v1",
    "summary": "Read an Indian mutual fund CAS PDF over HTTPS.",
    "description": "Send a CAS PDF (CAMS, KFintech, NSDL or CDSL), get back what the Sachfolio engine reads from it: holdings, transactions, checks, returns and, on request, capital gains. The PDF and its password exist only in memory for the one request; nothing is stored. Only reads that return a result count against a plan. Beta.",
    "contact": { "email": "developers@sachfolio.com", "url": "https://sachfolio.com/developers/" },
    "license": { "name": "Terms", "url": "https://sachfolio.com/developers/terms/" }
  },
  "servers": [{ "url": "https://api.sachfolio.com", "description": "Production (Mumbai)" }],
  "externalDocs": { "description": "API reference, error table and guides", "url": "https://sachfolio.com/developers/" },
  "tags": [
    { "name": "Read", "description": "Read a statement." },
    { "name": "Sandbox", "description": "Public answers for invented samples. No key, no file." },
    { "name": "Status", "description": "Health." },
    { "name": "Account", "description": "The developer dashboard's own calls (email code sign-in, then a session token). Not needed to read statements." }
  ],
  "paths": {
    "/v1/parse": {
      "post": {
        "tags": ["Read"],
        "operationId": "parseCas",
        "summary": "Read a CAS PDF",
        "description": "The body is the PDF itself. Up to 4 MB, 300 pages and 20 seconds of reading. Keys fail closed: a sandbox key, or no key id, may send only the invented sample statements.",
        "security": [{ "ApiKey": [] }],
        "parameters": [
          { "name": "x-pdf-password", "in": "header", "required": false, "description": "The PDF's password, if it has one. CAMS and KFintech: the one set on the request form. NSDL and CDSL: the first holder's PAN in capitals. Never logged.", "schema": { "type": "string" } },
          { "name": "format", "in": "query", "required": false, "description": "sachfolio (default): the engine's own JSON. casparser: casparser's CASData shape (page tags, checks and coverage are not in it).", "schema": { "type": "string", "enum": ["sachfolio", "casparser"], "default": "sachfolio" } },
          { "name": "include", "in": "query", "required": false, "description": "Comma-separated: analytics (default; checks, eligibility, XIRR) and gains (capital gains).", "schema": { "type": "string", "default": "analytics", "examples": ["analytics", "gains", "analytics,gains"] } },
          { "name": "redact", "in": "query", "required": false, "description": "true removes PAN, names, folio numbers, address and contact details; folio numbers in analytics and gains become folio-N. format=sachfolio only.", "schema": { "type": "string", "enum": ["true"] } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }
        },
        "responses": {
          "200": {
            "description": "The statement was read. A partial read is still 200: look at document.coverage, document.warnings and each check.",
            "headers": { "x-request-id": { "schema": { "type": "string" }, "description": "Same as request_id in the body." } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResult" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": ["Status"],
        "operationId": "health",
        "summary": "Health check",
        "description": "Answered by the gateway itself; no key, never runs (or bills) the function.",
        "security": [],
        "responses": {
          "200": {
            "description": "The API is up.",
            "content": { "application/json": { "schema": { "type": "object", "required": ["status", "api"], "properties": { "status": { "type": "string", "const": "ok" }, "api": { "type": "string", "const": "sachfolio.v1" } } } } }
          }
        }
      }
    },
    "/v1/samples/{name}": {
      "get": {
        "tags": ["Sandbox"],
        "operationId": "getSample",
        "summary": "The answer for an invented sample",
        "description": "Exactly what POST /v1/parse?include=analytics,gains returns for the sample PDF of that name (published at /developers/samples/). Add .casparser to the name for format=casparser. request_id is always \"sample\".",
        "security": [],
        "parameters": [
          { "name": "name", "in": "path", "required": true, "description": "dev-sample (a complete read), cams-detailed (a partial read), either with an optional .casparser suffix.", "schema": { "type": "string", "examples": ["dev-sample", "cams-detailed", "dev-sample.casparser"] } }
        ],
        "responses": {
          "200": { "description": "The sample's answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResult" } } } },
          "404": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/account/code": {
      "post": {
        "tags": ["Account"],
        "operationId": "accountSendCode",
        "summary": "Email a 6-digit sign-in code",
        "security": [],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } },
        "responses": { "200": { "$ref": "#/components/responses/AccountStatus" }, "400": { "$ref": "#/components/responses/AccountStatus" }, "429": { "$ref": "#/components/responses/AccountStatus" } }
      }
    },
    "/v1/account/session": {
      "post": {
        "tags": ["Account"],
        "operationId": "accountSignIn",
        "summary": "Exchange the code for a session token (12 hours)",
        "security": [],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "code"], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^\\d{6}$" } } } } } },
        "responses": {
          "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "type": "object", "required": ["token", "email", "expires"], "properties": { "token": { "type": "string" }, "email": { "type": "string" }, "expires": { "type": "string", "format": "date-time" } } } } } },
          "400": { "$ref": "#/components/responses/AccountStatus" },
          "401": { "$ref": "#/components/responses/AccountStatus" }
        }
      },
      "delete": {
        "tags": ["Account"],
        "operationId": "accountSignOut",
        "summary": "End the session",
        "security": [{ "Session": [] }],
        "responses": { "200": { "$ref": "#/components/responses/AccountStatus" }, "401": { "$ref": "#/components/responses/AccountStatus" } }
      }
    },
    "/v1/account/google": {
      "post": {
        "tags": ["Account"],
        "operationId": "accountGoogle",
        "summary": "Sign in with a Google ID token",
        "security": [],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "string", "description": "The Google ID token." } } } } } },
        "responses": { "200": { "description": "Signed in (same body as /v1/account/session).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AccountStatus" } }
      }
    },
    "/v1/account": {
      "get": {
        "tags": ["Account"],
        "operationId": "accountView",
        "summary": "The account's key, plans and usage",
        "security": [{ "Session": [] }],
        "responses": { "200": { "description": "Keys and passes.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AccountStatus" } }
      }
    },
    "/v1/account/rotate": {
      "post": {
        "tags": ["Account"],
        "operationId": "accountRotateKey",
        "summary": "Replace a key; the old one stops at once",
        "security": [{ "Session": [] }],
        "responses": { "200": { "description": "The new key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AccountStatus" }, "409": { "$ref": "#/components/responses/AccountStatus" } }
      }
    },
    "/v1/account/free": {
      "post": {
        "tags": ["Account"],
        "operationId": "accountClaimFree",
        "summary": "Claim the free plan (10 reads a month, once per account), after accepting the terms",
        "security": [{ "Session": [] }],
        "responses": { "200": { "description": "The account's key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AccountStatus" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your key, from the dashboard at https://api.sachfolio.com/dashboard. Without one, use GET /v1/samples/{name}." },
      "Session": { "type": "http", "scheme": "bearer", "description": "The token returned by /v1/account/session. Dashboard only." }
    },
    "schemas": {
      "ParseResult": {
        "type": "object",
        "required": ["api", "engine", "request_id", "document"],
        "properties": {
          "api": { "type": "string", "const": "sachfolio.v1", "description": "The API version. Check it before reading the rest." },
          "engine": { "type": "string", "description": "The engine version that read the statement." },
          "request_id": { "type": "string" },
          "document": {
            "type": "object",
            "description": "format=sachfolio: a CasDocument (JSON Schema: schema/cas-document.v1.schema.json in the package; every number is { raw, value, scale } with value an exact decimal string; coverage and warnings say what was left out). format=casparser: casparser's CASData (or NSDLCASData for depository statements).",
            "additionalProperties": true
          },
          "analytics": { "type": "object", "description": "Present unless include omits it. Checks, three-state eligibility per scheme and portfolio, and XIRR (schema xirr.v1). Use it to decide which holdings, returns and gains to show.", "additionalProperties": true },
          "gains": { "type": "object", "description": "Present with include=gains. Capital gains (schema gains.v1).", "additionalProperties": true }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "request_id"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "description": "Branch on this. The full list is in the error table at https://sachfolio.com/developers/ (docs/api/README.md).", "examples": ["NEED_PASSWORD", "INCORRECT_PASSWORD", "UNKNOWN_TEMPLATE", "TOO_LARGE", "SANDBOX_ONLY", "NO_CALLS_LEFT"] },
              "message": { "type": "string", "description": "Fixed wording, never anything from the statement." },
              "next_step": { "type": "string", "description": "What to do next. Sent by the function for every code; the gateway's own refusals (INVALID_API_KEY, THROTTLED, QUOTA_EXCEEDED) and the sandbox's carry it from the next stack update." }
            }
          },
          "request_id": { "type": "string" }
        }
      },
      "AccountStatus": { "type": "object", "properties": { "status": { "type": "string" } } }
    },
    "responses": {
      "Error": { "description": "An error in the API's shape. 400 bad request; 403 key or plan; 404 unknown route or sample; 413 too large; 422 a file the reader can't use; 429 too fast or no reads left; 500/502 our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "AccountStatus": { "description": "A short status message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatus" } } } }
    }
  }
}
