Create document

curl --request POST \
  --url https://api.gigstack.io/v2/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "contract",
  "name": "Contrato de servicios 2026 — Cliente ACME",
  "description": "Contrato marco de prestación de servicios",
  "fileUrl": "https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf",
  "storagePath": "teams/team_123/documents/contrato-acme.pdf",
  "fileName": "contrato-acme.pdf",
  "fileSize": 284913,
  "mimeType": "application/pdf",
  "validFrom": 1767225600000,
  "validUntil": 1798761600000,
  "tags": [
    "contrato",
    "acme"
  ],
  "linkedEntities": [
    {
      "entityType": "client",
      "entityId": "client_1234567890"
    }
  ],
  "analyzeWithAI": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'contract',
    name: 'Contrato de servicios 2026 — Cliente ACME',
    description: 'Contrato marco de prestación de servicios',
    fileUrl: 'https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf',
    storagePath: 'teams/team_123/documents/contrato-acme.pdf',
    fileName: 'contrato-acme.pdf',
    fileSize: 284913,
    mimeType: 'application/pdf',
    validFrom: 1767225600000,
    validUntil: 1798761600000,
    tags: ['contrato', 'acme'],
    linkedEntities: [{entityType: 'client', entityId: 'client_1234567890'}],
    analyzeWithAI: false
  })
};

fetch('https://api.gigstack.io/v2/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/documents"

payload = {
    "documentType": "contract",
    "name": "Contrato de servicios 2026 — Cliente ACME",
    "description": "Contrato marco de prestación de servicios",
    "fileUrl": "https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf",
    "storagePath": "teams/team_123/documents/contrato-acme.pdf",
    "fileName": "contrato-acme.pdf",
    "fileSize": 284913,
    "mimeType": "application/pdf",
    "validFrom": 1767225600000,
    "validUntil": 1798761600000,
    "tags": ["contrato", "acme"],
    "linkedEntities": [
        {
            "entityType": "client",
            "entityId": "client_1234567890"
        }
    ],
    "analyzeWithAI": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "id": "doc_1234567890",
    "document_type": "contract",
    "name": "Contrato de servicios 2026 — Cliente ACME",
    "description": "Contrato marco de prestación de servicios",
    "file_url": "https://firebasestorage.googleapis.com/v0/b/gigstackpro.appspot.com/o/teams%2Fteam_123%2Fdocuments%2Fcontrato-acme.pdf?alt=media&token=9f1c7d84-3b2e-4a56-8c0d-1e7f5b9a2c43",
    "file_name": "contrato-acme.pdf",
    "file_size": 284913,
    "mime_type": "application/pdf",
    "linked_entities": [
      {
        "entity_type": "client",
        "entity_id": "client_1234567890",
        "linked_at": 1767225600000
      }
    ],
    "compliance_status": "pending_review",
    "compliance_notes": null,
    "valid_from": 1767225600000,
    "valid_until": 1798761600000,
    "ai_extraction": null,
    "tags": [
      "contrato",
      "acme"
    ],
    "metadata": null,
    "created_at": 1767225600000,
    "created_by": "user_1234567890",
    "updated_at": null,
    "livemode": true
  },
  "message": "Document created successfully",
  "timestamp": 1767225600000
}

Documents

Create document

Availability: This operation has no configured public API gateway route and is not available through the documented base URL.

Register a document that has already been uploaded to storage. This endpoint records metadata — it does not accept the file itself; upload first and pass fileUrl and storagePath.

complianceStatus is always set server-side to pending_review on create and cannot be supplied here; change it later with PATCH /v2/documents/{id}.

Unknown top-level keys are rejected (400 validation_failed).

Create document

curl --request POST \
  --url https://api.gigstack.io/v2/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "contract",
  "name": "Contrato de servicios 2026 — Cliente ACME",
  "description": "Contrato marco de prestación de servicios",
  "fileUrl": "https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf",
  "storagePath": "teams/team_123/documents/contrato-acme.pdf",
  "fileName": "contrato-acme.pdf",
  "fileSize": 284913,
  "mimeType": "application/pdf",
  "validFrom": 1767225600000,
  "validUntil": 1798761600000,
  "tags": [
    "contrato",
    "acme"
  ],
  "linkedEntities": [
    {
      "entityType": "client",
      "entityId": "client_1234567890"
    }
  ],
  "analyzeWithAI": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'contract',
    name: 'Contrato de servicios 2026 — Cliente ACME',
    description: 'Contrato marco de prestación de servicios',
    fileUrl: 'https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf',
    storagePath: 'teams/team_123/documents/contrato-acme.pdf',
    fileName: 'contrato-acme.pdf',
    fileSize: 284913,
    mimeType: 'application/pdf',
    validFrom: 1767225600000,
    validUntil: 1798761600000,
    tags: ['contrato', 'acme'],
    linkedEntities: [{entityType: 'client', entityId: 'client_1234567890'}],
    analyzeWithAI: false
  })
};

fetch('https://api.gigstack.io/v2/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/documents"

payload = {
    "documentType": "contract",
    "name": "Contrato de servicios 2026 — Cliente ACME",
    "description": "Contrato marco de prestación de servicios",
    "fileUrl": "https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf",
    "storagePath": "teams/team_123/documents/contrato-acme.pdf",
    "fileName": "contrato-acme.pdf",
    "fileSize": 284913,
    "mimeType": "application/pdf",
    "validFrom": 1767225600000,
    "validUntil": 1798761600000,
    "tags": ["contrato", "acme"],
    "linkedEntities": [
        {
            "entityType": "client",
            "entityId": "client_1234567890"
        }
    ],
    "analyzeWithAI": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "id": "doc_1234567890",
    "document_type": "contract",
    "name": "Contrato de servicios 2026 — Cliente ACME",
    "description": "Contrato marco de prestación de servicios",
    "file_url": "https://firebasestorage.googleapis.com/v0/b/gigstackpro.appspot.com/o/teams%2Fteam_123%2Fdocuments%2Fcontrato-acme.pdf?alt=media&token=9f1c7d84-3b2e-4a56-8c0d-1e7f5b9a2c43",
    "file_name": "contrato-acme.pdf",
    "file_size": 284913,
    "mime_type": "application/pdf",
    "linked_entities": [
      {
        "entity_type": "client",
        "entity_id": "client_1234567890",
        "linked_at": 1767225600000
      }
    ],
    "compliance_status": "pending_review",
    "compliance_notes": null,
    "valid_from": 1767225600000,
    "valid_until": 1798761600000,
    "ai_extraction": null,
    "tags": [
      "contrato",
      "acme"
    ],
    "metadata": null,
    "created_at": 1767225600000,
    "created_by": "user_1234567890",
    "updated_at": null,
    "livemode": true
  },
  "message": "Document created successfully",
  "timestamp": 1767225600000
}

This operation exists in Discovery, but a matching public API gateway route is not configured. It is not currently available through the documented base URL.

Authorizations

Authorization

string

header

required

Authentication Method: HTTP Bearer token.

The runtime requires the literal Bearer prefix — a bare token in the Authorization header is rejected with 401 unauthorized.

Header Format: Authorization: Bearer YOUR_API_KEY

Your API key is a JWT. Live keys operate on live data (livemode: true); test keys operate on isolated test data (livemode: false).

Get your key at: app.gigstack.pro/settings?tab=api

Errors: credential failures are answered by the authentication layer with a raw { "message": … } body, not the standardized envelope — 401 for a missing, malformed or expired token, 403 for a revoked key or a plan without API access. See the Unauthorized and AuthForbidden responses.

Query Parameters

team

string

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a team other than the one your API key belongs to return 403 without it.

Only API keys can use it: an OAuth access token sent with another team's id is rejected with 403 Team mismatch with OAuth token.

Optional — omit it entirely unless you are acting on another team. It deliberately carries no example value so generated snippets do not emit ?team=undefined; when the parameter is absent, the team is derived from your API key.

Example: ?team=team_xyz789

Body

application/json

Metadata for a document that has already been uploaded to storage. Unknown top-level keys are rejected; metadata is the one object that accepts arbitrary keys. complianceStatus cannot be set here — it is always pending_review on create.

documentType

enum<string>

required

Kind of supporting document. Only these four values are accepted when creating a document. The internal type union also contains payment_confirmation, subscription_info, usage_report and cronograma, but those cannot be set through this API.

Available options:

contract,

delivery_proof,

payment_proof,

communication

Example:

"contract"

name

string

required

Example:

"Contrato de servicios 2026 — Cliente ACME"

fileUrl

string

required

Publicly resolvable URL of the stored file.

Example:

"https://storage.googleapis.com/gigstack-docs/team_123/contrato-acme.pdf"

storagePath

string

required

Path of the object inside the storage bucket.

Example:

"teams/team_123/documents/contrato-acme.pdf"

fileName

string

required

Example:

"contrato-acme.pdf"

description

string | null

Example:

"Contrato marco de prestación de servicios"

fileSize

number | null

Size in bytes.

Example:

284913

mimeType

string | null

Example:

"application/pdf"

linkedEntities

object[] | null

Entities to link the document to at creation time.

Show child attributes

validFrom

integer<int64> | null

Start of the document's validity window, epoch milliseconds.

Example:

1767225600000

validUntil

integer<int64> | null

End of the document's validity window, epoch milliseconds.

Example:

1798761600000

Response

Document created.

Standardized success envelope emitted by sendSuccessResponse.

success

enum<boolean>

required

Available options:

true

Example:

true

data

object

required

A document as returned by the documents endpoints (snake_case).

Show child attributes

timestamp

integer<int64>

required

Server time in epoch milliseconds (Luxon.now().toMillis()).

Example:

1767225600000

message

string

Human-readable summary. Present only when the handler supplies one.

Example:

"Operation completed successfully"

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Create document

Authorizations

Query Parameters

Body

Response