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

# Browse a connected source and import a file from your app

> Browse a SharePoint site or a OneDrive with a person's own sign-in, and import a file as an Athena asset. No third-party token leaves Athena.

An app can use an account its person already connected in Athena. Two routes browse a connected source and bring a file in as an asset. Athena makes every call to the outside system itself, with that person's own sign-in. Your app receives names, ids and asset ids. It never receives a Microsoft token or a signed download link.

The routes are in beta. They cover Microsoft 365 today: SharePoint sites and OneDrive.

| Route | What it does |
| - | - |
| `GET /api/v0/connectors/{catalog_asset_id}/items` | Lists one page of a connected account's sources, or of a source's libraries, folders and files. |
| `POST /api/v0/connectors/{catalog_asset_id}/items/import` | Brings one SharePoint file in as an asset, in a folder you name. |

## How this fits with the React SDK

`@athenaintel/react` lists a person's connected accounts and connects new ones: `useAthenaConnectors` and `<ConnectButton>`. These routes add what comes after: browsing a connected account and importing a file from it.

Every account `useAthenaConnectors` lists has a `catalogId`. That id is the `catalog_asset_id` these routes take.

> [!NOTE]
>
> `useAthenaConnectors` does not list Microsoft 365 accounts yet, and Microsoft 365 is the only connector these routes browse today.

## Who can call them

Call the routes with a credential the person holds themselves: their Athena sign-in, or an API key of their own. That is what an app built on `@athenaintel/react` holds for the person who created its computer, and for every member of an application.

A credential that a runtime holds for its person is refused with `403` before anything is read. That covers a computer's own key, a session VM's, a notebook's, a preview's and an agent's run. It also covers the viewer credential a member gets inside someone else's computer app.

Neither route depends on which workspace the person has open in Athena. Browsing and importing happen in the workspace the source belongs to. The person must be a member of that workspace.

## Browse a connected account

Browsing is one route, used at every level. Each item says which catalog to name next.

1. List the connected account's catalog. Its items are its sources: a OneDrive and the SharePoint sites the person connected.
2. List a source's `catalog_asset_id`. A SharePoint site answers its document libraries. A OneDrive answers its top-level folders and files.
3. To open a library or a folder, list the same `catalog_asset_id` with `folder_id` set to the item's `id`.

```bash theme={null}
curl "https://api.athenaintel.com/api/v0/connectors/$SOURCE_CATALOG_ID/items?folder_id=$FOLDER_ID" \
  -H "Authorization: Bearer $ATHENA_TOKEN"
```

```json theme={null}
{
  "catalog_asset_id": "asset_6c1f0a52-0d3b-4f0e-8a44-1f6f1c2f9b10",
  "kind": "sharepoint_site",
  "items": [
    {
      "id": "01YV4OGDCNIQCANEGYG5CJQGHPQ3RRODCH",
      "name": "Engagement letter.docx",
      "type": "file",
      "catalog_asset_id": "asset_6c1f0a52-0d3b-4f0e-8a44-1f6f1c2f9b10",
      "source_kind": null,
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size": 48213,
      "web_url": "https://contoso.sharepoint.com/sites/matters/Engagement%20letter.docx",
      "modified_at": "2026-11-18T09:12:44Z",
      "importable": true
    }
  ],
  "next_page_token": null
}
```

`kind` says what was listed: `microsoft_365` for a connected account, `sharepoint_site` or `onedrive` for a source.

| Item `type` | What it is | How to open it |
| - | - | - |
| `source` | A OneDrive or a SharePoint site. `source_kind` says which. | List its `catalog_asset_id` with no `folder_id`. |
| `library` | A SharePoint document library. | List its `catalog_asset_id` with `folder_id` set to its `id`. |
| `folder` | A folder. | List its `catalog_asset_id` with `folder_id` set to its `id`. |
| `file` | A file. | Import it when `importable` is `true`. |

When `next_page_token` is not `null`, pass it back as `page_token` with the same `catalog_asset_id` and `folder_id` for the next page. Treat the token as opaque.

`web_url` is the item's own address in SharePoint or OneDrive. Opening it asks for the person's sign-in there.

> [!NOTE]
>
> The person needs a connected account of their own for a source. Seeing a colleague's SharePoint catalog in Athena is not enough: the route answers `403` with code `connect_your_own`, and Athena asks Microsoft nothing.

## Import a file

```bash theme={null}
curl -X POST "https://api.athenaintel.com/api/v0/connectors/$SOURCE_CATALOG_ID/items/import" \
  -H "Authorization: Bearer $ATHENA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "01YV4OGDCNIQCANEGYG5CJQGHPQ3RRODCH",
    "folder_asset_id": "asset_b3a1c9d4-52f7-4a0b-9c1e-7d2e5f8a6b01"
  }'
```

```json theme={null}
{
  "asset_id": "asset_0a4e7c11-93b5-4c8e-b1f2-64d0a7e9c355",
  "title": "Engagement letter.docx",
  "asset_type": "document",
  "folder_asset_id": "asset_b3a1c9d4-52f7-4a0b-9c1e-7d2e5f8a6b01",
  "catalog_asset_id": "asset_6c1f0a52-0d3b-4f0e-8a44-1f6f1c2f9b10"
}
```

Athena downloads the file itself, with the person's own sign-in, and answers `201` with the new asset's id.

* **Folder.** `folder_asset_id` must be a folder in the source's workspace that the person can edit. Otherwise the route answers `403` or `400` and stores nothing.
* **Size.** A file can be at most 100 MiB. A larger one is refused with `413` and code `file_too_large` before Athena reads any of it.
* **Who can open it.** The new asset takes the sharing of where it is filed. Everyone who can open the Drive or the place the folder is in can open the asset, so import into a folder whose audience should see the file.
* **The copy.** A SharePoint file arrives as the same protected copy that **Import a copy** makes in Athena. It cannot be shared person by person, moved or renamed afterwards, and a share made on the folder itself for one person is not copied onto it. It keeps a record of the SharePoint file it came from.
* **OneDrive.** OneDrive files can be browsed but not imported yet. They are listed with `importable: false`, and an import answers `400` with code `import_not_supported`.

Each import makes a new asset. Importing the same file twice makes two copies.

## Handle refusals

A refusal carries a `detail` object with a `code` and a `message` written for a person. Branch on `code`.

| Status | `code` | What to do |
| - | - | - |
| `403` | `connect_your_own` | The person has not connected this source themselves. Have them connect their own account. |
| `403` | `needs_reconnect` | Their sign-in no longer works. Have them connect it again. |
| `403` | `not_enabled` | The workspace has the connector switched off. A workspace owner can turn it on. |
| `403` | `access_denied` | Athena or the outside system refuses this person for this source or item. |
| `404` | `source_not_found` | No catalog has this id, or it is in a workspace the person does not belong to. Both are answered alike. |
| `404` | `item_not_found` | The source has no item by that id that the person can open. |
| `400` | `unsupported_source` | The asset is not a connected account or a source these routes can browse. |
| `400` | `invalid_item_id`, `invalid_page_token`, `not_a_folder`, `not_a_file` | The request names something the source cannot list or import. |
| `400` | `import_not_supported` | Files of this source cannot be imported yet. |
| `400` | `invalid_folder` | `folder_asset_id` is not a folder asset in Athena. |
| `413` | `file_too_large` | The file is over 100 MiB. `detail.max_bytes` carries the limit. |
| `415` | `file_not_supported` | Athena does not store files of this type. |
| `502` | `source_unavailable` | The outside system failed. Try again. |
| `503` | `source_busy` | The outside system is throttling, or Athena is renewing the sign-in. Wait for the `Retry-After` header, then try again. |

Some refusals carry a plain sentence in `detail` instead of an object, so read `detail` as either. They are a credential the person does not hold themselves (`403`), a workspace that is no longer active (`403`), a destination folder they cannot see or edit (`403`) or that is archived or no folder (`400`), and a request body over 16 KiB (`413`).

A request that does not validate answers `422`, and its `detail` is a list of the fields at fault.

## What Athena keeps on its side

* The person's Microsoft sign-in stays encrypted in Athena, on that person's own connected account. Athena uses it for each call and never returns it.
* Microsoft decides what the person can see on every call, with their current permissions there.
* Browsing stores nothing. An import stores the new asset and its record of where the file came from.

The full request and response schemas are in the [API reference](https://docs.athenaintel.com/api-reference).


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