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

# Connector Data

> Manage data sources attached to assessments

# Connector Data

Connector data represents the knowledge base documents attached to an assessment - the data sources candidates can search during the task. Documents can be marked as **signal** (useful) or left as **noise** (distractors) to test candidate discernment.

## List Available Connectors

```
GET /api/connectors
```

Returns the available connector manifests for a given assessment (based on its connector configuration).

<ParamField query="assessmentId" type="string" required>
  The assessment to list connectors for
</ParamField>

<Accordion title="Response">
  Each item is the assessment's stored `ConnectorConfig`. Note `id` is the connector's own identifier; the `type` field is what holds the connector kind (e.g. `"enterprise_search"`). `source` is `"builtin"` for the packaged fakes or `"mcp"` for a real MCP server; MCP entries also carry `mcpServerUrl`/`mcpTransport`.

  ```json theme={null}
  {
    "connectors": [
      {
        "id": "conn_1",
        "type": "enterprise_search",
        "name": "Enterprise Search",
        "description": "Search company knowledge base",
        "icon": "search",
        "authType": "none",
        "source": "builtin"
      }
    ]
  }
  ```
</Accordion>

***

## List Connector Data

```
GET /api/assessments/:id/connector-data
```

<Accordion title="Response">
  ```json theme={null}
  {
    "connectorData": [
      {
        "id": "uuid",
        "connectorType": "enterprise_search",
        "name": "Q3 Revenue Report",
        "description": "Quarterly financial results...",
        "isSignal": true,
        "createdAt": "2025-01-15T10:00:00Z",
        "dataFiles": [
          { "id": "uuid", "title": "q3-summary.md", "isSignal": true, "fileExt": "md" }
        ]
      }
    ]
  }
  ```
</Accordion>

***

## Get Connector Data Item

```
GET /api/assessments/:id/connector-data/:docId
```

Returns the full connector data record including file contents.

<Accordion title="Response">
  ```json theme={null}
  {
    "connectorData": {
      "id": "uuid",
      "assessmentId": "uuid",
      "connectorType": "enterprise_search",
      "name": "Q3 Revenue Report",
      "description": "...",
      "dataFiles": [
        {
          "id": "uuid",
          "title": "report.csv",
          "content": "extracted plain text used for search",
          "type": "table",
          "metadata": {},
          "isSignal": true,
          "storagePath": "org/assessment/123-report.csv",
          "fileExt": "csv",
          "mime": "text/csv"
        }
      ],
      "isSignal": true,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  }
  ```
</Accordion>

***

## Create Connector Data

```
POST /api/assessments/:id/connector-data
```

<ParamField body="connectorType" type="string" required>
  Connector type (e.g. `enterprise_search`, `company_wiki`, `market_data`, `crm_data`)
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the data source
</ParamField>

<ParamField body="description" type="string">
  Description of the data source
</ParamField>

<ParamField body="dataFiles" type="array">
  Array of file objects with `title`, `content`, and optional `metadata`. (A legacy `name` key is still read as a fallback, but `title` is canonical.)
</ParamField>

<ParamField body="isSignal" type="boolean" default="false">
  Whether this is a signal document (useful for the task)
</ParamField>

<Accordion title="Response - 201 Created">
  ```json theme={null}
  {
    "connectorData": { "..." }
  }
  ```
</Accordion>

***

## Upload Connector Data File

```
POST /api/assessments/:id/connector-data/upload
```

<Warning>
  Document upload into connectors is **currently disabled** (`CONNECTOR_DOC_UPLOAD_ENABLED = false`). Every call returns `403 { "error": { "code": "forbidden", "message": "Document upload into connectors is temporarily disabled." } }`. Use `POST /api/assessments/:id/connector-data` with inline `dataFiles` instead. The behavior below describes the endpoint when re-enabled.
</Warning>

Upload a real document (`.docx`, `.pptx`, `.xlsx`, `.csv`, or `.pdf`) into a connector. The file is dual-stored: the real bytes go to the private `documents` Storage bucket, and its extracted plain text is saved to `data_files[].content` for search.

Two targeting modes:

* Pass `connectorId` to append the file to an existing connector's file list.
* Omit `connectorId` and pass `connectorType` (+ optional `connectorName`) to create a new connector row with this as its first file.

**Request:** `multipart/form-data`

<ParamField body="file" type="file" required>
  The file to upload (`.docx`, `.pptx`, `.xlsx`, `.csv`, `.pdf`)
</ParamField>

<ParamField body="connectorId" type="string">
  Existing connector row id to append this file to
</ParamField>

<ParamField body="connectorType" type="string">
  Connector type for a new connector row (required if `connectorId` is not given)
</ParamField>

<ParamField body="connectorName" type="string">
  Display name for a new connector row (defaults to the filename)
</ParamField>

<ParamField body="isSignal" type="string">
  `"true"` or `"false"`
</ParamField>

<Accordion title="Response - 201 Created">
  ```json theme={null}
  {
    "connectorData": {
      "id": "uuid",
      "name": "Meeting notes",
      "connectorType": "enterprise_search",
      "isSignal": false,
      "createdAt": "2025-01-15T10:00:00Z",
      "fileId": "uuid"
    }
  }
  ```
</Accordion>

***

## Delete File From Connector

```
DELETE /api/assessments/:id/connector-data/:docId/files/:fileId
```

Removes a single file from a connector's file list (and its real file in Storage, if any). If this was the connector's last file, the whole connector row is deleted too.

<Accordion title="Response">
  ```json theme={null}
  {
    "ok": true,
    "deletedConnector": false
  }
  ```
</Accordion>

***

## Rename / Toggle Signal on a File

```
PATCH /api/assessments/:id/connector-data/:docId/files/:fileId
```

Renames a single file and/or flips its signal/noise flag in place, inside a connector's file list (a connector row can hold several real files — this addresses one of them without touching the rest).

<ParamField body="title" type="string">New file title</ParamField>
<ParamField body="isSignal" type="boolean">Updated signal flag for this file</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "connectorData": { "..." }
  }
  ```
</Accordion>

***

## Update Connector Data

```
PATCH /api/assessments/:id/connector-data/:docId
```

<ParamField body="name" type="string">Updated name</ParamField>
<ParamField body="description" type="string">Updated description</ParamField>
<ParamField body="isSignal" type="boolean">Updated signal flag</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "connectorData": { "..." }
  }
  ```
</Accordion>

***

## Delete Connector Data

```
DELETE /api/assessments/:id/connector-data/:docId
```

<Accordion title="Response">
  ```json theme={null}
  {
    "ok": true
  }
  ```
</Accordion>