# Skywalk API

> REST API for AppFolio Property Manager data

Skywalk API provides programmatic access to AppFolio Property Manager data via a JSON REST API. It enables property management companies and PropTech developers to read and write AppFolio data from any language or tool.

## Quick Start

Base URL: https://api.skywalkapi.com/v1/
Auth: Pass your API key in the `X-API-Key` header with every request.
Rate Limit: 1 request per second per API key.

Example:
```
curl https://api.skywalkapi.com/v1/properties \
  -H "X-API-Key: YOUR-API-KEY"
```

## Important: Async Polling Pattern

GET requests return cached data. If data is stale, the response will have `meta.status: "updating"` and a background job fetches fresh data from AppFolio. Poll the same URL every 10 seconds until `meta.status` is `"ok"`.

Status values:
- `ok` — Data is fresh and ready
- `stale` — Cached data returned, but a refresh has been triggered
- `updating` — Data is being fetched; poll again shortly

To force a fresh fetch, set the `X-API-MAX-AGE` header to `120` which will ensure the data is no older than 120 seconds.

## Documentation

- Full docs: https://docs.skywalkapi.com/docs/api
- Authentication: https://docs.skywalkapi.com/docs/api/reference/auth
- Response format: https://docs.skywalkapi.com/docs/api/reference/response-details
- Data caching: https://docs.skywalkapi.com/docs/api/reference/data-caching
- Webhooks: https://docs.skywalkapi.com/docs/api/reference/webhooks
- AI Agents guide: https://docs.skywalkapi.com/docs/guides/ai-agents

## GET Endpoints

- GET /v1/properties — Get a list of properties
- GET /v1/property-groups — Get a list of property groups
- GET /v1/owners — Get a list of owners
- GET /v1/units — Get a list of units
- GET /v1/unit-vacancies — Unit vacancy details
- GET /v1/unit-photos — Get a list of unit photos
- GET /v1/tenants — Get a list of tenants
- GET /v1/lease-history — Get lease history
- GET /v1/vendors — Get a list of vendors
- GET /v1/work-orders — Get work orders
- GET /v1/gl-accounts — Get a list of GL accounts
- GET /v1/cash-flow — Get the cash flow statement
- GET /v1/balance-sheet — Get the balance sheet statement
- GET /v1/annual-budget-comparative — Get the annual budget comparative statement
- GET /v1/bank-accounts — Get a list of bank accounts
- GET /v1/bank-account-activity — Get bank account activity for a given bank account
- GET /v1/tenant-ledger — Get tenant ledger for a given tenant
- GET /v1/rent-roll — Get rent roll of properties
- GET /v1/rent-roll-recurring — Get list of recurring rent roll charges
- GET /v1/rent-roll-itemized — Get itemized rent roll of properties
- GET /v1/guest-cards — Get guest cards
- GET /v1/lead-source-tracking — Get metrics on lead sources
- GET /v1/rental-applications — Get rental applications

## POST Endpoints

- POST /v1/tenant-charge — Create a tenant charge for a given tenant

## Response Format

```json
{
  "meta": {
    "status": "ok",
    "path": "/v1/properties",
    "count": 42,
    "lastUpdated": 1712000000,
    "page": 1
  },
  "links": {
    "next": "/v1/properties?cursor=abc123"
  },
  "data": [
    { "...": "..." }
  ]
}
```

## Pagination

When results span multiple pages, `links.next` contains a cursor URL. Follow it to get the next page. Continue until `links.next` is absent.

## Common Headers

| Header | Required | Description |
|---|---|---|
| X-API-Key | Yes | Your API key |
| X-API-MAX-AGE | No | Max acceptable cache age in seconds (default: 86400) |
| X-API-PROCESSING-MODE | No | "default" (24s timeout) or "longer" (120s timeout) |
| X-API-NOTIFY-URL | No | Webhook URL — receive a POST when your data is ready |

## Common Query Parameters

| Parameter | Description |
|---|---|
| cursor | Pagination cursor from links.next |
| propertyIds | Filter by property IDs (comma-separated, where supported) |