> ## Documentation Index > Fetch the complete documentation index at: https://docs.tented.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a contact import > Create a contact import session. Two modes, selected by `source`: - **`upload`** — returns a presigned S3 `PUT` URL. Upload the raw CSV bytes to `upload_url` with the returned `upload_headers` before the URL expires (`expires_in_seconds`, 15 minutes). Source files up to 350 MB are supported. Only CSV content types are accepted (`text/csv`, `application/csv`, `application/vnd.ms-excel`, `text/plain`). - **`rows`** — send rows inline as JSON objects (1–1,000 rows). Keys are column headers; the union of keys across all rows becomes the CSV header row. Values are stringified; `null` becomes an empty string. Inline request bodies are limited to 5 MB — larger bodies are rejected with `413` (this keeps requests below the platform's 6 MB payload ceiling, so treat ~5 MB as the practical limit and use `upload` mode for anything bigger). After creating a session, call `POST /v1/contacts/imports/{sessionId}/preview` to get proposed column mappings, then `POST /v1/contacts/imports/{sessionId}/execute` to run the import. Sessions expire after 7 days and can each be executed once. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contacts/imports openapi: 3.1.0 info: title: Tented API version: 1.0.0 description: >- The Tented public API: generate, publish, and manage AI-built web pages (tents), and run the email platform — contacts, reusable emails, one-time blasts, and triggered flows. ## Authentication Authenticate every request with a workspace API key: `Authorization: Bearer `. Keys are created in **Workspace Settings → API Keys** and are scoped to a single workspace. ## Asynchronous work Tent generation, bulk creation, and email AI generation return `202 Accepted` immediately. Poll the corresponding status endpoint (`GET /v1/tents/{tentId}`, `GET /v1/bulk-jobs/{bulkJobId}`, `GET /v1/emails/{emailId}/generations/{generationId}`) — no more than every 10 seconds. ## Pagination Email listings use cursor pagination (`cursor`/`next_cursor`). Blast, flow, and member listings use page pagination (`page`/`limit` with a `pagination` object in the response). ## Conventions Request and response fields are snake_case, with two exceptions: analytics query parameters (`tentIdOrAlias`, `daysBack`) and segment rule trees (camelCase keys such as `listId` and `timeWindow`). contact: name: Tented Support email: support@tented.ai servers: - url: https://api.tented.ai description: Production security: - bearerAuth: [] tags: - name: Tents description: >- Create, edit, publish, and manage AI-generated pages, including asset uploads and bulk creation. - name: Analytics description: Traffic analytics for single tents and the whole workspace. - name: Contacts description: >- Batch create, update, and delete contacts. Up to 25 items per request with per-item results. - name: Emails description: >- Reusable email content: AI generation, direct HTML edits, plain-text control, and approval. - name: Email Blasts description: >- One-time sends to an audience: compose, schedule, track engagement, export recipients. - name: Triggered Flows description: >- Multi-step automations that enroll contacts on triggers and move them through a step graph. - name: Contact Imports - name: Contact Fields - name: Contact Lists - name: Email Templates - name: Tent Templates description: >- Reusable, AI-editable tent layouts. Create from HTML or an existing tent, iterate with AI, approve, and clone. Approved tent templates seed new tents. paths: /v1/contacts/imports: post: tags: - Contact Imports summary: Start a contact import description: >- Create a contact import session. Two modes, selected by `source`: - **`upload`** — returns a presigned S3 `PUT` URL. Upload the raw CSV bytes to `upload_url` with the returned `upload_headers` before the URL expires (`expires_in_seconds`, 15 minutes). Source files up to 350 MB are supported. Only CSV content types are accepted (`text/csv`, `application/csv`, `application/vnd.ms-excel`, `text/plain`). - **`rows`** — send rows inline as JSON objects (1–1,000 rows). Keys are column headers; the union of keys across all rows becomes the CSV header row. Values are stringified; `null` becomes an empty string. Inline request bodies are limited to 5 MB — larger bodies are rejected with `413` (this keeps requests below the platform's 6 MB payload ceiling, so treat ~5 MB as the practical limit and use `upload` mode for anything bigger). After creating a session, call `POST /v1/contacts/imports/{sessionId}/preview` to get proposed column mappings, then `POST /v1/contacts/imports/{sessionId}/execute` to run the import. Sessions expire after 7 days and can each be executed once. operationId: create-contact-import requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/ContactImportUploadRequest' - $ref: '#/components/schemas/ContactImportRowsRequest' discriminator: propertyName: source mapping: upload: $ref: '#/components/schemas/ContactImportUploadRequest' rows: $ref: '#/components/schemas/ContactImportRowsRequest' responses: '201': description: >- Import session created. `upload` mode returns a presigned upload URL; `rows` mode returns the stored row count. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ContactImportUploadSession' - $ref: '#/components/schemas/ContactImportRowsSession' '400': description: >- Bad request — invalid parameters or request body. Validation failures include `details.issues` with per-field messages. Also returned when `content_type` is not a supported CSV content type (`Only CSV uploads are supported`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing, malformed, revoked, or expired API key. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: >- Payload too large — inline `rows` request bodies are limited to 5 MB. Use `source: "upload"` for larger imports. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ContactImportUploadRequest: type: object title: Upload mode properties: source: type: string enum: - upload description: 'Import mode: upload a CSV file via a presigned URL.' file_name: type: string minLength: 1 maxLength: 255 default: contacts.csv description: >- File name to associate with the import (shown in run details and used to name the results export). content_type: type: string minLength: 1 maxLength: 255 default: text/csv description: >- Content type of the upcoming upload. Must be one of `text/csv`, `application/csv`, `application/vnd.ms-excel`, or `text/plain`; anything else is rejected with `400`. The presigned URL is bound to this content type — send the same `Content-Type` header on the `PUT`. required: - source ContactImportRowsRequest: type: object title: Inline rows mode properties: source: type: string enum: - rows description: 'Import mode: send rows inline as JSON.' file_name: type: string minLength: 1 maxLength: 255 description: >- Optional file name to associate with the import. Defaults to `contacts-.csv`. rows: type: array items: type: object additionalProperties: type: - string - number - boolean - 'null' description: >- Cell value. Non-string values are stringified; `null` becomes an empty string. description: 'One row: keys are column headers, values are cell values.' minItems: 1 maxItems: 1000 description: >- Rows to import (1–1,000). The union of keys across all rows becomes the CSV header row. The total request body must stay under 5 MB. required: - source - rows ContactImportUploadSession: type: object title: Upload session properties: import_session_id: type: string format: uuid description: Import session ID. Use it for the preview and execute calls. file_name: type: string description: File name associated with the import. upload_url: type: string description: >- Presigned S3 `PUT` URL. Upload the raw CSV bytes here (no auth header needed — the URL is self-authorizing). upload_headers: type: object additionalProperties: type: string description: >- Headers to send with the `PUT` (currently the `Content-Type` the URL was signed for). expires_in_seconds: type: integer description: Seconds until `upload_url` expires (900 = 15 minutes). required: - import_session_id - file_name - upload_url - upload_headers - expires_in_seconds ContactImportRowsSession: type: object title: Rows session properties: import_session_id: type: string format: uuid description: Import session ID. Use it for the preview and execute calls. file_name: type: string description: File name associated with the import. row_count: type: integer description: Number of rows stored from the request. required: - import_session_id - file_name - row_count Error: type: object properties: error: type: string description: Human-readable error message. error_code: type: string description: >- Stable machine-readable error code (present on email, blast, flow, and related endpoints, e.g. `campaign_not_ready`, `generation_in_progress`). message: type: string description: Additional human-readable context (present on some tent endpoints). code: type: string description: >- Machine-readable code used by tent creation errors (e.g. `INVALID_PROMPT_INTENT`). details: type: object additionalProperties: true description: >- Additional error context. Validation errors include `issues`: an array of `{ path, message }` objects. limit: type: integer description: Plan limit that was hit (present on `429` publish-limit errors). current: type: integer description: >- Current usage against the limit (present on `429` publish-limit errors). required: - error description: >- Error response. All errors include `error`; the other fields vary by endpoint group. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Workspace API key, e.g. `Authorization: Bearer tented_...`. Create keys in Workspace Settings → API Keys. ````