Create sheet | SpreadSpace

curl -X POST https://api.spreadspace.app/api/markets/sheets \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "kind": "custom",
  "name": "Margin bridge",
  "doc": {
    "v": 1,
    "filers": {},
    "sheets": [
      {
        "id": "s1a2b3c4",
        "name": "Margin bridge",
        "rows": [
          {
            "id": "r0000001"
          },
          {
            "id": "r0000002"
          }
        ],
        "cols": [
          {
            "id": "c0000001",
            "w": 14
          },
          {
            "id": "c0000002"
          }
        ],
        "cells": {
          "r0000001:c0000001": {
            "v": "Net sales"
          },
          "r0000001:c0000002": {
            "v": 418250000
          },
          "r0000002:c0000001": {
            "v": "Gross profit"
          },
          "r0000002:c0000002": {
            "v": 129657500
          }
        },
        "frozen": {
          "rows": 1,
          "cols": 1
        },
        "merges": [],
        "groups": []
      }
    ],
    "names": {},
    "scenarios": {},
    "activeScenario": null,
    "sens": {}
  },
  "is_original": false,
  "comp_id": "4e1f7a2b9c3d5e6f8a0b1c2d"
}'

{
  "sheet": {
    "id": "8d4f1a6b3c5e7f9a1b2c4d6e",
    "kind": "custom",
    "name": "Margin bridge",
    "is_original": false,
    "version": 1,
    "created_at": "2026-03-09T11:04:27.550318+00:00",
    "updated_at": "2026-03-09T11:04:27.550318+00:00",
    "cik": null,
    "comp_id": "4e1f7a2b9c3d5e6f8a0b1c2d",
    "spread_board_id": null
  },
  "doc": {
    "v": 1,
    "filers": {},
    "sheets": [
      {
        "id": "s1a2b3c4",
        "name": "Margin bridge",
        "rows": [
          {
            "id": "r0000001"
          },
          {
            "id": "r0000002"
          }
        ],
        "cols": [
          {
            "id": "c0000001",
            "w": 14
          },
          {
            "id": "c0000002"
          }
        ],
        "cells": {
          "r0000001:c0000001": {
            "v": "Net sales"
          },
          "r0000001:c0000002": {
            "v": 418250000
          },
          "r0000002:c0000001": {
            "v": "Gross profit"
          },
          "r0000002:c0000002": {
            "v": 129657500
          }
        },
        "frozen": {
          "rows": 1,
          "cols": 1
        },
        "merges": [],
        "groups": []
      }
    ],
    "names": {},
    "scenarios": {},
    "activeScenario": null,
    "sens": {}
  }
}

Creates a saved sheet at version 1: an annual or quarterly sheet names a company by its CIK, a comparison, custom or spread sheet names a comp; the document is a JSON object of at most 2,000,000 bytes. An optional client-minted id makes a create asked again answer 200 with the sheet that already landed. Needs a Market research subscription and markets:write.

Requires the markets:write scope. Rate limit: 200 requests per minute per key (the api lane).

Authentication

AuthorizationBearer

Bearer token. Use ss_live_… for live data or ss_test_… for the sandbox (test mode). See Authentication.

Request

The request's cancellation token.

kindstringRequired

What the sheet is: annual, quarterly, comparison, custom or spread. A spread sheet made here follows no canvas; the canvas’s own sheet route makes the one that does.

namestringRequired

The sheet's name, 1 to 200 characters after trimming.

docanyRequired

The SpreadSheet document, a JSON object of at most 2,000,000 UTF-8 bytes.

is_originalbooleanRequiredDefaults to false

Whether this is the company’s original sheet (2026-10-29): needs cik and a kind of annual or quarterly. When the company’s original of that kind already stands, the create answers 200 with that sheet, unchanged, so a SpreadSheet’s first open never makes a second one.

idstring or nullOptional

An optional client-minted id, 24 lowercase hexadecimal characters: a create asked again with it answers the sheet that already landed instead of making a second one.

cikstring or nullOptional

The company’s CIK, one to ten digits, with or without its leading zeros, of a registrant in the store: required on an annual or quarterly sheet, refused on the others.

comp_idstring or nullOptional

The id of a comp the caller can see: required on a comparison, custom or spread sheet, refused on an annual or quarterly one.

Response headers

X-Request-IDstringOptional

Correlation ID for this request. Quote it in support tickets.

Idempotency-Replayboolean

Set to true when the response is replayed from the idempotency cache for a request that re-presented an Idempotency-Key it had already used. Absent on the original (winner) response. A replay repeats the original status and body. When the original could not be stored (an unhandled server fault, or a body over the 1 MiB replay cap) the replay is an error envelope that says so; the operation is never re-run under the same key.

SpreadSpace-VersionstringOptional

The API surface version the server resolved for this request. Always present, regardless of whether the client supplied the request-side SpreadSpace-Version header. Default: 2026-10-07.

RateLimit-Limitinteger

Request budget of the endpoint’s rate-limit policy per 60-second sliding window. See Rate limits.

RateLimit-Remaininginteger

Requests left in the current window. Suppressed on 429 responses produced outside the rate limiter (for example a usage throttle), where a remaining budget would be misleading.

RateLimit-Resetinteger

Seconds until a guaranteed-fresh window.

RateLimit-PolicystringOptional

The active policy in limit;w=window-seconds form.

Response

sheetobject

The sheet.

docany

The SpreadSheet document as saved, a JSON object.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error

Authentication

Headers

Request

Response headers

Response

Errors