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

# Introduction

> Aptly is a property management platform. This API gives external tools, scripts, and AI agents direct read/write access to your boards, cards, contacts, and more.

<Note>
  **Documentation Index**
  Fetch the complete index of all available pages at: [https://docs.getaptly.com/llms.txt](https://docs.getaptly.com/llms.txt)
  Start here to discover all endpoints before exploring further.
</Note>

Aptly is a property management platform that helps companies run leasing, maintenance, resident operations, and more. The Aptly API gives external tools, scripts, and AI agents direct read/write access to your Aptly data.

Use this API to sync data from a PMS, build a custom integration, automate workflows, or connect an AI agent to your boards.

## How Aptly is structured

Understanding the data model makes the API much easier to use.

| Object | Description |
| - | - |
| **Company** | The top-level account. Your API key is scoped to a company. |
| **Board** | A workspace that tracks a specific workflow. Examples: a Leasing board for prospects and applications, a Maintenance board for work orders, a Residents board for active leases. Identified by a `boardId` (UUID). |
| **Card** | An individual record on a board. A card might represent a lead, a lease, a work order, or a vendor. Identified by `_id`. |
| **Field** | A structured data column on a board. Each field has a UUID key, a human-readable label, and a type (text, date, money, multiselect, etc.). Fetch the board schema to get the full list before reading or writing. |
| **Contact** | A person record (prospect, resident, owner, vendor) scoped to the company. Contacts can be linked to cards across multiple boards. |

## What you can do

* **Read and list cards** — paginate through all cards on a board or fetch a single card by ID
* **Create and update cards** — push records into any board using field keys from the schema
* **Manage contacts** — create, update, and look up people records by email across all boards
* **Add comments and files** — attach notes or documents to any card
* **Add tab views** — embed external URLs as tabs directly on a board
* **Read the board schema** — discover field keys and types before reading or writing data

## Who this API is for

**Developers** building integrations between Aptly and other tools like PMS platforms, telephony systems, or CRMs.

**AI agents** that need to read board data, create or update cards, look up contacts, or take action based on property management workflows. The Aptly MCP server is the recommended interface for agentic use.

**Operators and automators** running scripts or no-code workflows to push data in and out of Aptly boards.

## MCP server

Aptly exposes a Model Context Protocol (MCP) server for AI agent integrations. This is the recommended way to connect LLMs and AI agents to Aptly.

### MCP server URL

```
https://mcp.getaptly.com/mcp
```

## MCP quick start

Connect an AI assistant to Aptly in a couple of minutes. You only need the [MCP server URL](#mcp-server-url) above. Aptly signs you in with OAuth, so there are no API keys to create or paste.

<Note>
  **Permissions:** the Aptly MCP server has the same broad permissions as the user who signs in. Anything that person can see and do in Aptly, the connected assistant can too, and it is not limited to particular boards or actions. Connect with an account whose access you are comfortable giving the assistant. If you need to restrict access, use the Core API with a scoped API key instead.
</Note>

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open Connectors">
        In Claude Desktop, open **Settings** and select **Connectors**.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector**. Enter a name such as `Aptly` and paste the MCP server URL:

        ```
        https://mcp.getaptly.com/mcp
        ```

        Click **Add**.
      </Step>

      <Step title="Sign in to Aptly">
        Click **Connect**. A browser window opens. Sign in to Aptly and approve access.
      </Step>

      <Step title="Try it">
        Start a new chat, make sure the Aptly connector is turned on, and ask something like *"Search my Aptly boards for Maintenance"* or *"Show my latest unread emails"*.
      </Step>
    </Steps>

    <Note>
      On Claude Team and Enterprise plans, an organization Owner may need to add the connector for the organization first. Members then find it under **Connectors** and click **Connect**.
    </Note>
  </Tab>

  <Tab title="Codex desktop">
    <Steps>
      <Step title="Open MCP servers">
        In the Codex desktop app, open **Settings** and select **MCP servers**.
      </Step>

      <Step title="Add the server">
        Click **Add server**. Enter a name such as `aptly`, choose **Streamable HTTP**, and enter the URL:

        ```
        https://mcp.getaptly.com/mcp
        ```

        Save, then click **Restart** when asked.
      </Step>

      <Step title="Sign in to Aptly">
        In the server list, click **Authenticate** next to `aptly`. A browser window opens. Sign in to Aptly and approve access.
      </Step>

      <Step title="Try it">
        In a new thread, type `/mcp` to confirm `aptly` is connected, then ask something like *"Search my Aptly boards for Maintenance"*.
      </Step>
    </Steps>

    <Accordion title="Prefer the command line or a config file?">
      The Codex desktop app, CLI and IDE extension share one configuration, so you can set it up once from the terminal instead:

      ```bash theme={null}
      codex mcp add aptly --url https://mcp.getaptly.com/mcp
      codex mcp login aptly
      ```

      Or add it to `~/.codex/config.toml` and then run `codex mcp login aptly`:

      ```toml theme={null}
      [mcp_servers.aptly]
      url = "https://mcp.getaptly.com/mcp"
      ```
    </Accordion>
  </Tab>
</Tabs>

See [MCP tools](/mcp-server) for the full list of what the assistant can do.

## Core API Base URL

Aptly also exposes a REST API for developers and AI agents. The REST API has enhanced capabilities that may work better for more structured use cases.

Unlike the MCP server, the Core API has fine-grained permissions. Create API keys in Aptly under **Setup → Developer** and choose exactly what each key can reach:

* **Boards** and **Inboxes**: limit a key to specific boards and inboxes, or leave them empty to allow all.
* **Permissions**: whether the key can **Read**, **Insert** and **Update**.
* **Resource Access** toggles: **Knowledge**, **Contacts**, **Users**, **Templates**, **Routing Groups**, **Create Boards** and **Automations**. Create Boards and Automations are off by default, so a key can't create boards or automations until you turn them on.

Give each integration its own key with only the access it needs.

```
https://core-api.getaptly.com
```

## Core API quick start

Use the REST API directly from scripts and integrations with an API key. Set each key's permissions under **Setup → Developer** in Aptly.

<Steps>
  <Step title="Enable the API for your board">
    In Aptly, open the board → **Card Sources** → **API** and toggle the API on.
  </Step>

  <Step title="Create an API key">
    Under the API section, click **Create New Key**, give it a name, and copy the key value.
  </Step>

  <Step title="Fetch the schema">
    ```bash theme={null}
    curl https://core-api.getaptly.com/api/schema/{boardId} \
      -H "x-token: YOUR_API_KEY"
    ```

    This returns the list of field keys you'll need for reading and writing cards.
  </Step>

  <Step title="Create a card">
    ```bash theme={null}
    curl -X POST https://core-api.getaptly.com/api/board/{boardId} \
      -H "x-token: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "John Smith", "<fieldKey>": "<value>" }'
    ```
  </Step>
</Steps>

## Using Rest API with Claude/Codex

Coding assistants such as Claude Code and Codex can call the Core API for you from your computer. You give them your API key in a local `.env` file and a short instruction file that tells them how to use it.

<Note>
  This works with tools that can run commands on your machine: **Claude Code** (the terminal app, or the Code tab in Claude Desktop) and **Codex** (desktop app, CLI or IDE extension). The regular chat in Claude Desktop can't read local files, so use the [MCP server](#mcp-quick-start) there instead.
</Note>

<Steps>
  <Step title="Create a scoped API key">
    In Aptly, create an API key under **Setup → Developer** and give it only the access the assistant needs (boards, inboxes, and read, insert or update). See [Core API Base URL](#core-api-base-url) for the options. Copy the key.
  </Step>

  <Step title="Save the key in a .env file">
    In the folder you open in Claude Code or Codex, create a file named `.env`:

    ```bash theme={null}
    APTLY_API_KEY=paste-your-api-key-here
    ```

    Then make sure the file is never committed to git. If the folder is a git repository, add it to `.gitignore`:

    ```bash theme={null}
    echo ".env" >> .gitignore
    ```
  </Step>

  <Step title="Tell the assistant how to use it">
    Add the instructions below to an instruction file in the same folder. Claude Code reads `CLAUDE.md` and Codex reads `AGENTS.md`. Create whichever you use (or both).

    ```markdown theme={null}
    ## Aptly API

    - The Aptly Core API is at https://core-api.getaptly.com. My API key is `APTLY_API_KEY` in the `.env` file in this folder.
    - Load the key in the same command you run the request in, then send it in the `x-token` header:

      set -a; source .env; set +a
      curl -s https://core-api.getaptly.com/api/boards -H "x-token: $APTLY_API_KEY"

    - Never print, echo, log or commit the API key, and never put it in a file other than `.env`.
    - The list of endpoints is at https://docs.getaptly.com/llms.txt. Read it before calling an endpoint you haven't used.
    - Ask me before running requests that create, change or delete data.
    ```
  </Step>

  <Step title="Ask for something">
    Open the folder in your tool and ask, for example, *"List my Aptly boards"* or *"Show the fields on my Maintenance board"*. The first time, the tool will ask your permission to run the request.
  </Step>
</Steps>

<Tabs>
  <Tab title="Claude Code">
    * Open the folder with `claude` in your terminal, or choose it in the **Code** tab of Claude Desktop.
    * Claude Code asks before running each command. When it asks to run a read request such as listing boards, you can choose to always allow that kind of command. Keep requests that create, change or delete data on "ask".
  </Tab>

  <Tab title="Codex">
    * Open the folder in the Codex desktop app, or run `codex` in it from your terminal.
    * Codex runs commands in a sandbox that blocks network access by default, so calls to the API will be refused. Either approve network access when Codex asks, or allow it for your workspace in `~/.codex/config.toml`:

      ```toml theme={null}
      sandbox_mode = "workspace-write"

      [sandbox_workspace_write]
      network_access = true
      ```

      On macOS the setting has been reported to not take effect in some versions. If requests still fail, approve the command when Codex asks.
    * Codex hides environment variables with `KEY`, `SECRET` or `TOKEN` in their name from the commands it runs. That's why the instructions load the file with `source .env` inside each command, rather than relying on your shell environment.
  </Tab>
</Tabs>

<Warning>
  Anything the assistant can read, it can send to its AI provider as part of the conversation. Don't ask it to open or print your `.env` file. Use a key with the least access needed, and revoke the key in **Setup → Developer** if it is ever exposed.
</Warning>


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