Create table - Autotouch AI

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

The request model accepts userId and organizationId for compatibility, but the route derives ownership from the authenticated principal and ignores those supplied identifiers. The nested tableContract is validated inside the command model; route code does not translate command-model validation errors to a documented client status. The response illustration is abridged; TableOut can also include timestamps, lifecycle/deletion fields, schema classification, and the server-derived table contract.

Body parameters

namerequired
string
Non-blank table display name; trimmed by the backend.
metadata · optional
object
Optional JSON object stored as metadata; defaults to an empty object.
tableContract · optional
ResearchTableContractV1
Optional contract. Required fields: record_semantics, row_behavior, creation_origin, artifact_role, classification; entity_scope can be inferred from anchors. See definition.
userId · optional
string
Accepted for compatibility but ignored; owner comes from authentication.
organizationId · optional
string
Accepted for compatibility but ignored; organization comes from authentication.

Name	Type	Description
namerequired	string	Non-blank table display name; trimmed by the backend.
metadata	object	Optional JSON object stored as metadata; defaults to an empty object.
tableContract	ResearchTableContractV1	Optional contract. Required fields: record_semantics, row_behavior, creation_origin, artifact_role, classification; entity_scope can be inferred from anchors. See definition.
userId	string	Accepted for compatibility but ignored; owner comes from authentication.
organizationId	string	Accepted for compatibility but ignored; organization comes from authentication.

Definitions

ResearchTableContractV1

Extra fields are rejected. version defaults to 1; arrays default empty. Required fields are shown below.

Fields

version · optional
integer
Literal 1; defaults to 1.
record_semanticsrequired
string
One of entity, event, relationship, generic.
entity_scope · optional
string
One of person, company, person_company, none, mixed, unknown; inferred from anchors when omitted, otherwise defaults to unknown.
anchors · optional
array<string>
Items: company or person; default [].
record_kinds · optional
array<string>
String array; default [].
canonical_signals · optional
array<CanonicalSignalRef>
Each item requires signal_type (nonblank); optional signal_subtype; default [].
evidence_kinds · optional
array<string>
String array; default [].
row_behaviorrequired
string
One of mutable_set, append_log, snapshot.
creation_originrequired
string
One of blank, csv_import, crm_import, api, integration, scheduled_agent, derived, unknown.
artifact_rolerequired
string
One of standalone, source, result, routed_output.
classificationrequired
TableContractClassification
See nested definition.

Name	Type	Description
version	integer	Literal 1; defaults to 1.
record_semanticsrequired	string	One of entity, event, relationship, generic.
entity_scope	string	One of person, company, person_company, none, mixed, unknown; inferred from anchors when omitted, otherwise defaults to unknown.
anchors	array<string>	Items: company or person; default [].
record_kinds	array<string>	String array; default [].
canonical_signals	array<CanonicalSignalRef>	Each item requires signal_type (nonblank); optional signal_subtype; default [].
evidence_kinds	array<string>	String array; default [].
row_behaviorrequired	string	One of mutable_set, append_log, snapshot.
creation_originrequired	string	One of blank, csv_import, crm_import, api, integration, scheduled_agent, derived, unknown.
artifact_rolerequired	string	One of standalone, source, result, routed_output.
classificationrequired	TableContractClassification	See nested definition.

TableContractClassification

Extra fields are rejected.

Fields

sourcerequired
string
One of creator, runtime, migration, user.
version · optional
integer
Literal 1; defaults to 1.
confidencerequired
number
Inclusive range 0.0–1.0.
evidence · optional
array<string>
Defaults to []; labels normalized/deduplicated.
conflicts · optional
array<string>
Defaults to []; labels normalized/deduplicated.

Name	Type	Description
sourcerequired	string	One of creator, runtime, migration, user.
version	integer	Literal 1; defaults to 1.
confidencerequired	number	Inclusive range 0.0–1.0.
evidence	array<string>	Defaults to []; labels normalized/deduplicated.
conflicts	array<string>	Defaults to []; labels normalized/deduplicated.

CanonicalSignalRef

Extra fields are rejected.

Fields

signal_typerequired
string
Must normalize to a known sales signal type.
signal_subtype · optional
string
Optional normalized subtype; blank becomes null.

Name	Type	Description
signal_typerequired	string	Must normalize to a known sales signal type.
signal_subtype	string	Optional normalized subtype; blank becomes null.

Errors

Status	Meaning
401	Invalid API key or missing auth.
403	API key lacks required scope: tables:write.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GitHub Prospects - Q1",
      "metadata": {"source":"github_agent"}
    }'

Request body

json

{
    "name": "GitHub Prospects - Q1",
    "metadata": {
      "source": "github_agent",
      "campaign": "q1-2026"
    }
  }

Response example

json

{
    "id": "67bd8c39c7d3e80f0a95b560",
    "name": "GitHub Prospects - Q1",
    "columns": [],
    "userId": "67a...",
    "organizationId": "67b...",
    "metadata": {
      "source": "github_agent",
      "campaign": "q1-2026"
    }
  }