> ## Documentation Index > Fetch the complete documentation index at: https://paymanai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Start a durable account read > Available only when CONNECT_STRUCTURED_READS is enabled. Queue an explicitly read-only operation for one authorized connection. A new requestId creates a fresh read; repeating it joins the same job. Requires financial_data:read. Snapshot transactions require a date window of at most 94 days inclusive. ## OpenAPI ````yaml /api-reference/openapi.yaml post /connect/reads openapi: 3.0.3 info: title: Payman Connect API version: 0.1.0 description: >- The HTTP contract behind Payman Connect: exchange a customer's consent for a grant, send actions against the accounts it reaches, and follow an approval to its receipt. Every call carries your app key, and every call after the exchange carries the grant. Non-2xx responses share one `ApiError` envelope. Most integrations never write these calls: the SDK speaks them for you. servers: - url: https://paygent-cloud-server-production.up.railway.app description: Current hosted Railway deployment - url: http://localhost:8891 description: A local stack security: - bearerAuth: [] tags: - name: Connect description: >- Third-party access. A registered app presents its app key together with a grant token its customer consented to; the pair reaches exactly the one deployment the grant names, and nothing else on this API. paths: /connect/reads: post: tags: - Connect summary: Start a durable account read description: >- Available only when CONNECT_STRUCTURED_READS is enabled. Queue an explicitly read-only operation for one authorized connection. A new requestId creates a fresh read; repeating it joins the same job. Requires financial_data:read. Snapshot transactions require a date window of at most 94 days inclusive. operationId: createStructuredRead requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - deploymentId - read properties: deploymentId: type: string format: uuid requestId: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9._:-]+$ intent: $ref: '#/components/schemas/FinancialReadIntent' allPages: type: boolean default: false read: type: object required: - operation - arguments additionalProperties: false properties: operation: type: string enum: - list_accounts - get_account - list_transactions - sync_transactions arguments: type: object additionalProperties: false description: >- get_account requires accountId. list_accounts permits only limit and cursor. list_transactions requires accountId, startDate and endDate. sync_transactions requires accountId and accepts cursor and limit (Plaid only). Use the full provider account ID from the same connection. properties: accountId: type: string minLength: 1 maxLength: 4096 cursor: type: string minLength: 1 maxLength: 4096 limit: type: integer minimum: 1 maximum: 500 default: 200 startDate: type: string format: date endDate: type: string format: date responses: '202': description: >- Saved job identity, state, intent, and status URL. Poll the result endpoint. content: application/json: schema: type: object additionalProperties: true required: - intent properties: intent: $ref: '#/components/schemas/FinancialReadIntent' '400': description: Unsupported operation or invalid bounded parameters '401': description: Invalid or expired Connect credentials '403': description: >- Connection is outside the grant or financial_data:read scope is absent '409': description: requestId was reused for a different request or expired security: - connectAppKey: [] connectGrant: [] - connectGrant: [] components: schemas: FinancialReadIntent: type: object nullable: true additionalProperties: false required: - purpose description: >- Optional caller-supplied context for record keeping. Include the known purpose by default, or omit/use null when unknown. This is not an instruction or a verified identity. Avoid credentials and full conversations. Stored encrypted with the read job for 24 hours; save the JSON metadata for longer retention. properties: purpose: type: string minLength: 1 maxLength: 1000 description: Why the user wants these records. taskId: type: string minLength: 1 maxLength: 128 description: >- Shared task ID linking related reads, distinct from each read's requestId. requestedBy: type: string minLength: 1 maxLength: 128 description: >- Caller-reported bot or application label. Authentication still determines the caller's identity. securitySchemes: connectAppKey: type: apiKey in: header name: x-paygent-connect-app-key description: >- A Connect app key (`pgc_app_…`), identifying the registered third-party app. Always presented together with `connectGrant` — the pair is one credential, and either half alone is refused. Accepted on the `/connect/*` surface only. connectGrant: type: apiKey in: header name: x-paygent-connect-grant description: >- A Connect grant token (`pgc_grant_…`): one user's consent for the presenting app to reach one deployment. Every failure mode — missing, malformed, revoked, expired, or paired with the wrong app key — answers the same 401 `invalid_connect_credentials`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.