Introduction

Documentation Index Fetch the complete index of all available pages at: https://docs.getaptly.com/llms.txt Start here to discover all endpoints before exploring further.

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 above. Aptly signs you in with OAuth, so there are no API keys to create or paste.

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.

Claude Desktop
Codex desktop

Open Connectors

In Claude Desktop, open Settings and select Connectors.

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.

Click Connect. A browser window opens. Sign in to Aptly and approve access.

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”.

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.

Open MCP servers

In the Codex desktop app, open Settings and select MCP servers.

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.

In the server list, click Authenticate next to aptly. A browser window opens. Sign in to Aptly and approve access.

Try it

In a new thread, type /mcp to confirm aptly is connected, then ask something like “Search my Aptly boards for Maintenance”.

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:

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:

[mcp_servers.aptly]
url = "https://mcp.getaptly.com/mcp"

See MCP tools 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.

Enable the API for your board

In Aptly, open the board → Card Sources → API and toggle the API on.

Create an API key

Under the API section, click Create New Key, give it a name, and copy the key value.

Fetch the schema

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.

Create a card

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>" }'

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.

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 there instead.

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 for the options. Copy the key.

Save the key in a .env file

In the folder you open in Claude Code or Codex, create a file named .env:

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:

echo ".env" >> .gitignore

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).

## 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.

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.

Claude Code
Codex

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”.

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:
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.

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.

Getting Started

Guides

Reference

How Aptly is structured

What you can do

Who this API is for

MCP server

MCP server URL

MCP quick start

Core API Base URL

Core API quick start

Using Rest API with Claude/Codex

​How Aptly is structured

​What you can do

​Who this API is for

​MCP server

​MCP server URL

​MCP quick start

​Core API Base URL

​Core API quick start

​Using Rest API with Claude/Codex

How Aptly is structured

What you can do

Who this API is for

MCP server

MCP server URL

MCP quick start

Core API Base URL

Core API quick start

Using Rest API with Claude/Codex