API reference

Files

This object represents files hosted on Stripe's servers. You can upload files with the create file request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a Sigma scheduled query). Related guide: File upload guide

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Base URL
https://api.knoxapi.com

Create a file

POST/v1/files

To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file. All of Stripe’s officially supported Client libraries support sending multipart/form-data.

Parameters

No parameters.

Returns

The file object.

POST /v1/files
curl -X POST https://api.knoxapi.com/v1/files \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "expires_at": 1234567890,
  "filename": "file_1Pgag2B7WZ01zgkWITx3dIQc",
  "id": "file_1Pgag2B7WZ01zgkWITx3dIQc",
  "links": {
    "data": [
      {
        "created": 1721954068,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1Pgc76B7WZ01zgkWPhd77i13",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3Rfb0Jkam9sNHdEZUpXRHUzSGhXNTRkZDI500qGiHOxxv"
      },
      {
        "created": 1721950452,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgbAmB7WZ01zgkW3pu4fR4P",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWm9xd1F0dDBtbXQ4Z1dKNzlONGh1eWpB00LxTveMUm"
      },
      {
        "created": 1721950452,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgbAmB7WZ01zgkWwbZvcvQ8",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfSG53SzROQjd1eW5CalpJNWZXVTNCWkJP00ezD17LP8"
      },
      {
        "created": 1721949627,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgaxTB7WZ01zgkWjUTJLaVH",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfbUJMZHhvRlhBUjJ5Sk44RnNZdU5pc3JW00dVoJx2Tt"
      },
      {
        "created": 1721949626,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgaxSB7WZ01zgkWTnPuQ3DJ",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfN1NDVWF0ZXB5bUQxZDVOOU00UWRjMEJW00s1CyRs6z"
      },
      {
        "created": 1721948546,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1Pgag2B7WZ01zgkWT1SijPEZ",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWFc0dDAzZVB6eExGV3kzMWpwaUFqZDlW0041cNM6yo"
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/file_links?file=file_1Pgag2B7WZ01zgkWITx3dIQc"
  },
  "object": "file",
  "purpose": "dispute_evidence",
  "size": 9863,
  "title": null,
  "type": "png",
  "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/v1/files/file_1Pgag2B7WZ01zgkWITx3dIQc/contents"
}

List all files

GET/v1/files

Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.

Query parameters

  • createdobject | integer

    Only return files that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • purposestring

    Filter queries by the file purpose. If you don't provide a purpose, the queries return unfiltered files.

    Possible values
    • account_requirement
    • additional_verification
    • business_icon
    • business_logo
    • customer_signature
    • dispute_evidence
    • document_provider_identity_document
    • finance_report_run
    • financial_account_statement
    • identity_document
    • identity_document_downloadable
    • issuing_regulatory_reporting
    • pci_document
    • platform_terms_of_service
    • selfie
    • sigma_scheduled_query
    • and 5 more
  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of file objects.

GET /v1/files
curl -G https://api.knoxapi.com/v1/files \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "expires_at": 1234567890,
      "filename": "file_1Pgag2B7WZ01zgkWITx3dIQc",
      "id": "file_1Pgag2B7WZ01zgkWITx3dIQc",
      "links": {
        "data": [
          {
            "created": 1721954068,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1Pgc76B7WZ01zgkWPhd77i13",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3Rfb0Jkam9sNHdEZUpXRHUzSGhXNTRkZDI500qGiHOxxv"
          },
          {
            "created": 1721950452,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1PgbAmB7WZ01zgkW3pu4fR4P",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWm9xd1F0dDBtbXQ4Z1dKNzlONGh1eWpB00LxTveMUm"
          },
          {
            "created": 1721950452,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1PgbAmB7WZ01zgkWwbZvcvQ8",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfSG53SzROQjd1eW5CalpJNWZXVTNCWkJP00ezD17LP8"
          },
          {
            "created": 1721949627,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1PgaxTB7WZ01zgkWjUTJLaVH",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfbUJMZHhvRlhBUjJ5Sk44RnNZdU5pc3JW00dVoJx2Tt"
          },
          {
            "created": 1721949626,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1PgaxSB7WZ01zgkWTnPuQ3DJ",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfN1NDVWF0ZXB5bUQxZDVOOU00UWRjMEJW00s1CyRs6z"
          },
          {
            "created": 1721948546,
            "expired": false,
            "expires_at": null,
            "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
            "id": "link_1Pgag2B7WZ01zgkWT1SijPEZ",
            "livemode": false,
            "metadata": {},
            "object": "file_link",
            "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWFc0dDAzZVB6eExGV3kzMWpwaUFqZDlW0041cNM6yo"
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/file_links?file=file_1Pgag2B7WZ01zgkWITx3dIQc"
      },
      "object": "file",
      "purpose": "dispute_evidence",
      "size": 9863,
      "title": null,
      "type": "png",
      "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/v1/files/file_1Pgag2B7WZ01zgkWITx3dIQc/contents"
    }
  ]
}

Retrieve a file

GET/v1/files/{file}

Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to access file contents.

Path parameters

  • filestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The file object.

GET /v1/files/{file}
curl https://api.knoxapi.com/v1/files/file_1Pgag2B7WZ01zgkWITx3dIQc \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "expires_at": 1234567890,
  "filename": "file_1Pgag2B7WZ01zgkWITx3dIQc",
  "id": "file_1Pgag2B7WZ01zgkWITx3dIQc",
  "links": {
    "data": [
      {
        "created": 1721954068,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1Pgc76B7WZ01zgkWPhd77i13",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3Rfb0Jkam9sNHdEZUpXRHUzSGhXNTRkZDI500qGiHOxxv"
      },
      {
        "created": 1721950452,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgbAmB7WZ01zgkW3pu4fR4P",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWm9xd1F0dDBtbXQ4Z1dKNzlONGh1eWpB00LxTveMUm"
      },
      {
        "created": 1721950452,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgbAmB7WZ01zgkWwbZvcvQ8",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfSG53SzROQjd1eW5CalpJNWZXVTNCWkJP00ezD17LP8"
      },
      {
        "created": 1721949627,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgaxTB7WZ01zgkWjUTJLaVH",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfbUJMZHhvRlhBUjJ5Sk44RnNZdU5pc3JW00dVoJx2Tt"
      },
      {
        "created": 1721949626,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1PgaxSB7WZ01zgkWTnPuQ3DJ",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfN1NDVWF0ZXB5bUQxZDVOOU00UWRjMEJW00s1CyRs6z"
      },
      {
        "created": 1721948546,
        "expired": false,
        "expires_at": null,
        "file": "file_1Pgag2B7WZ01zgkWITx3dIQc",
        "id": "link_1Pgag2B7WZ01zgkWT1SijPEZ",
        "livemode": false,
        "metadata": {},
        "object": "file_link",
        "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/links/MDB8YWNjdF8xUGdhZlRCN1daMDF6Z2tXfGZsX3Rlc3RfWFc0dDAzZVB6eExGV3kzMWpwaUFqZDlW0041cNM6yo"
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/file_links?file=file_1Pgag2B7WZ01zgkWITx3dIQc"
  },
  "object": "file",
  "purpose": "dispute_evidence",
  "size": 9863,
  "title": null,
  "type": "png",
  "url": "https://sangeekp-15t6ai--upload-mydev.dev.stripe.me/v1/files/file_1Pgag2B7WZ01zgkWITx3dIQc/contents"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.