> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tables via the API

> Create, fill and query tables from your own code with the REST API or the Python SDK

Manage tables from your own code with the [REST API](/api-reference/v1--tables/list-tables) or the [Python SDK](/sdk/resources/tables). Requests authenticate with a workspace API key in the `X-API-KEY` header, and Tables must be enabled for your organization.

## What you can do

| Area | What you can do |
| :- | :- |
| **Tables** | [List](/api-reference/v1--tables/list-tables), [create](/api-reference/v1--tables/create-table), [get](/api-reference/v1--tables/get-table), [update](/api-reference/v1--tables/update-table), [delete](/api-reference/v1--tables/delete-table), [stats](/api-reference/v1--tables/get-table-stats) |
| **Columns** | [Add](/api-reference/v1--tables/add-column), [rename](/api-reference/v1--tables/rename-column), [change type](/api-reference/v1--tables/change-column-type), [update label](/api-reference/v1--tables/update-column-label), [reorder](/api-reference/v1--tables/reorder-columns), [drop](/api-reference/v1--tables/drop-column) |
| **Rows** | [List](/api-reference/v1--tables/list-rows), [insert one](/api-reference/v1--tables/insert-row), [insert many](/api-reference/v1--tables/insert-rows), [update](/api-reference/v1--tables/update-row), [delete](/api-reference/v1--tables/delete-row), [clear](/api-reference/v1--tables/clear-rows) |
| **Files** | [Import CSV](/api-reference/v1--tables/import-csv), [export CSV](/api-reference/v1--tables/export-table-csv) |
| **SQL** | [Run a read-only query](/api-reference/v1--tables/query-tables) |

Listing tables also returns [platform tables](/platform/tables/platform-tables), which can be read and queried but not changed.

## Example

Create a table, add two rows, then query it.

<CodeGroup>
  ```python Python SDK theme={null}
  from noxus_sdk.client import Client

  client = Client(api_key="your_api_key_here")

  table = client.tables.create(
      name="Customers",
      columns=[
          {"name": "email", "type": "string"},
          {"name": "signups", "type": "number"},
      ],
  )

  table.insert_rows([
      {"email": "ana@example.com", "signups": 3},
      {"email": "ben@example.com", "signups": 7},
  ])

  result = client.tables.query(
      "SELECT email, signups FROM customers ORDER BY signups DESC"
  )
  for row in result.rows:
      print(row)
  ```

  ```bash cURL theme={null}
  # 1. Create the table (the response includes its id and sql_name)
  curl -X POST https://backend.noxus.ai/v1/tables \
    -H "X-API-KEY: $NOXUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Customers",
      "columns": [
        {"name": "email", "type": "string"},
        {"name": "signups", "type": "number"}
      ]
    }'

  # 2. Insert rows
  curl -X POST https://backend.noxus.ai/v1/tables/$TABLE_ID/rows/bulk \
    -H "X-API-KEY: $NOXUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"rows": [
      {"email": "ana@example.com", "signups": 3},
      {"email": "ben@example.com", "signups": 7}
    ]}'

  # 3. Query
  curl -X POST https://backend.noxus.ai/v1/tables/query \
    -H "X-API-KEY: $NOXUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"sql": "SELECT email, signups FROM customers ORDER BY signups DESC"}'
  ```
</CodeGroup>

SQL refers to tables by their identifier (`customers` here), not their display name. See [how the identifier is generated](/platform/tables/creating-tables).

## Limits

* **Insert many**: up to 1,000 rows per call. For larger loads, split into batches or use CSV import.
* **List rows**: up to 500 rows per page.
* **Queries**: read-only, with the same rules, 10-second timeout and 10,000-row cap as the app. See [SQL Queries](/platform/tables/using/sql).
* **Rate limits**: table writes and queries have their own rate-limit groups, `tables_write` and `tables_query`. See [Rate limiting](/deployment/configuration/rate-limiting).

## Next steps

<CardGroup cols={3}>
  <Card title="API cookbook" icon="book-open" href="/api-reference/cookbook/tables">
    Copy-paste recipes in Python, Node and cURL.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/v1--tables/list-tables">
    Every tables endpoint, with request and response schemas.
  </Card>

  <Card title="Tables in the SDK" icon="terminal" href="/sdk/resources/tables">
    The full `client.tables` reference.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.