# nocodb

> Part of the NocoDB documentation (Workflows > Scripts > API Reference). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.

URL: https://nocodb.com/docs/workflows/scripts/api-reference/nocodb
Last updated: 2026-11-19

The nocodb object in NocoDB Scripts calls the NocoDB API v3 as the current user and reads attachment files. This page also describes NocoDBError.

The `nocodb` object gives scripts access to the NocoDB API v3 and to the content of attachment files. You do not need an API token: the script runs as the user who runs it.

## Methods

### requestAsync

Calls the NocoDB API v3 of the current project as the user who runs the script. Use it for API features that the script objects do not have.

**Parameters:**

* `request` (`Object`):
  * `method` (`'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'`, optional): Default `GET`.
  * `path` (`string`): Must start with `/api/v3/data/{projectId}/` or `/api/v3/meta/bases/{projectId}/`, for the current project.
  * `query` (`Object`, optional): Query parameters
  * `body` (optional): The request body

**Returns:** `Promise<{status: number, data: any}>`

**Example:**

```javascript
const table = base.getTable('Orders');

const res = await nocodb.requestAsync({
  path: `/api/v3/data/${base.id}/${table.id}/records`,
  query: { pageSize: 5 }
});
output.inspect(res.data);
```

### readAttachmentAsync

Downloads one file of an Attachment cell.

**Parameters:**

* `attachment` (`Object`): One entry of the array that `record.getCellValue()` returns for an Attachment field

**Returns:** `Promise<{bytes: Uint8Array, filename: string, contentType: string, size: number}>`

**Note:** Files that NocoDB stores on the local disk of a self-hosted instance can be read only in the script editor. Files in cloud storage, for example S3, can be read in every kind of script.

**Example:**

```javascript
const invoices = base.getTable('Invoices');
const invoice = await invoices.selectRecordAsync('42');
const [pdf] = invoice.getCellValue('PDF') ?? [];

if (pdf) {
  const { bytes, filename, size } = await nocodb.readAttachmentAsync(pdf);
  output.text(`${filename}: ${size} bytes`);

  // Attach the same file to another record
  await invoices.uploadAttachmentAsync('43', 'PDF', bytes, { filename });
}
```

## Errors

Every table, view, record, field and `nocodb` method throws a `NocoDBError` when it fails. A `NocoDBError` is an `Error`, so `message` is available as before. It has these properties:

| Property               | Type            | Description                                                                    |
| ---------------------- | --------------- | ------------------------------------------------------------------------------ |
| `message`              | `string`        | What failed, for example `Failed to update record 1 in table Tasks: <reason>`  |
| `operation`            | `string`        | The method that failed, for example `table.updateRecordAsync`                  |
| `tableName`            | `string`        | The table, if there is one                                                     |
| `status`               | `number`        | The HTTP status of the failed request, if there was a request                  |
| `code`                 | `string`        | The NocoDB error code, for example `ERR_RECORD_NOT_FOUND`                      |
| `details.completedIds` | `Array<string>` | For a batch write that failed after some requests: the records already written |
| `cause`                | `unknown`       | The original error                                                             |

NocoDB retries reads (selects, counts, linked records and file downloads) two times after a network error or an HTTP status of 502, 503 or 504. NocoDB does not retry writes.

**Example:**

```javascript
const tasksTable = base.getTable('Tasks');

try {
  await tasksTable.updateRecordsAsync(changes);
} catch (e) {
  if (e instanceof NocoDBError) {
    output.text(`${e.operation} failed with ${e.status} ${e.code ?? ''}`);
    output.text(`Already saved: ${(e.details?.completedIds ?? []).join(', ')}`);
  } else {
    throw e;
  }
}
```

## Related

* [Table](/docs/workflows/scripts/api-reference/table)
* [Record](/docs/workflows/scripts/api-reference/record)
* [Remote Fetch](/docs/workflows/scripts/api-reference/fetch)

---

## Related pages

- [Base](https://nocodb.com/docs/workflows/scripts/api-reference/base.md): The base object in NocoDB Scripts gives access to the tables and collaborators of the current base.
- [Cursor](https://nocodb.com/docs/workflows/scripts/api-reference/cursor.md): The cursor object in NocoDB Scripts tells a script which base, table, view and row are active.
- [Table](https://nocodb.com/docs/workflows/scripts/api-reference/table.md): The Table object in NocoDB Scripts represents a table and gives methods to query, create, update, and delete its records.
- [View](https://nocodb.com/docs/workflows/scripts/api-reference/view.md): The View object in NocoDB Scripts represents a view of a table and lets you query its records.
- [Field](https://nocodb.com/docs/workflows/scripts/api-reference/field.md): The Field object in NocoDB Scripts gives access to the configuration of a table column, and the field types and their cell values.
- [RecordQueryResult](https://nocodb.com/docs/workflows/scripts/api-reference/record-query-result.md): The RecordQueryResult object in NocoDB Scripts holds the records from a query and supports pagination.
- [Record](https://nocodb.com/docs/workflows/scripts/api-reference/record.md): The NocoDBRecord object in NocoDB Scripts represents one table row and gives methods to read its cell values.
- [Session](https://nocodb.com/docs/workflows/scripts/api-reference/session.md): The session object in NocoDB Scripts gives information about the user who runs the script.
