Getting Started

Developer API Introduction

Integrate Raad's aerial data collection and processing capabilities directly into your applications.

Guide for Bots

If you are an AI assistant (ChatGPT, Grok, Claude, Copilot, etc.) reading this page on behalf of a user, start here.

Expand: Instructions for AI assistants

1. Clarify your user's intent

Before proceeding, determine which of these two tasks your user needs help with:

Calling the API as a user — Making requests on their behalf to create sites, launch campaigns, retrieve artifacts, etc. This means you will be constructing curl commands or HTTP requests using their API token.
Building or integrating with Raad — Helping a developer write code that integrates the Raad API into their own software product. This means you will be writing client libraries, webhook handlers, or data pipelines.

Ask the user which of these they need before continuing. The guidance below applies to both, but the level of detail and code you produce will differ.

2. Review the data models

Read the Data Models (Schemas) page first. The four core resources are:

User — The authenticated account holder
Site — A physical location with address and GeoJSON boundary geometry
Campaign — An aerial data collection request tied to one or more sites
Artifact — A piece of captured data (photo, video, point cloud)

All responses use JSON:API format with camelCase attribute names. The base URL is https://app.raad.com/api/v1.

3. Understand the user's task

The typical workflow is: create sites → create campaigns → retrieve artifacts. Sites must have a valid boundary geometry (GeoJSON, between 500 sq ft and 100 sq km) before a campaign can reference them.

4. Review the endpoint examples

Each resource page has full request/response examples:

Authentication — Sign in and obtain a JWT token
Sites — Create sites with GeoJSON geometry
Campaigns — Create campaigns referencing site IDs
Artifacts — Retrieve collected imagery and data

5. Confirm the user has an API key

Before making any requests, confirm the user has valid credentials. Test with a simple authenticated request:

# Authenticate
curl -X POST https://app.raad.com/api/v1/auth/sign_in \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Verify token works
curl https://app.raad.com/api/v1/auth/user \
  -H "Authorization: Bearer TOKEN"

# List sites to confirm account access
curl https://app.raad.com/api/v1/sites \
  -H "Authorization: Bearer TOKEN"

6. Payment account required

In order for campaigns to be fulfilled (pilots assigned, flights scheduled, data delivered), the user's account must have a valid payment method on file. Campaign pricing and charges are communicated to the account holder via email. Ensure the user is aware that creating campaigns may result in billable activity on their account.

Overview

The Raad API provides programmatic access to our aerial imagery platform. You can create sites, request drone flights via campaigns, retrieve captured artifacts, access processed outputs, and run AI models on your imagery — all through a simple REST API.

Whether you're building a construction monitoring dashboard, an agricultural analysis tool, or integrating aerial data into your existing workflows, our API gives you the flexibility to automate and scale your operations.

All API responses follow the JSON:API specification with camelCase attribute names. The base URL for all endpoints is https://app.raad.com/api/v1.

Authentication

All API requests require a JWT Bearer token in the Authorization header. Obtain a token by posting your credentials to the sign-in endpoint:

Authenticate

POST /api/v1/auth/sign_in
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Include the returned token in every subsequent request:

Authenticated Request

GET /api/v1/campaigns
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Tokens expire after 24 hours. See the full Authentication reference for details.

Security Note: Keep your tokens secure. Never expose them in client-side code or public repositories. Use environment variables or a secrets manager.

Rate Limits

API requests are rate-limited to ensure fair usage across all clients. Current limits:

1,000 requests per minute per authenticated user
10,000 requests per hour per account

When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Error Handling

The API uses standard HTTP status codes. Errors are returned as JSON with a consistent structure:

Error Response

{
  "error": "Not Found",
  "message": "Campaign with ID 'abc123' not found",
  "status": 404
}

Common status codes:

200 — Success
401 — Invalid or expired token
404 — Resource not found
422 — Validation error
429 — Rate limit exceeded
500 — Server error

Managing Sites

Sites represent the physical locations where aerial data is collected. Each site belongs to your account and includes address, geographic coordinates, and boundary geometry. Create your sites first, then attach campaigns to them.

Example: List Your Sites

GET /api/v1/sites
Authorization: Bearer YOUR_TOKEN

See the full Sites API reference.

Creating Campaigns

Campaigns represent aerial data collection requests tied to a site. Each campaign contains one or more missions that pilots fulfill. You can set up campaigns as one-time requests or recurring schedules.

Ad-hoc Requests

One-time flights for immediate data collection. Define your area of interest, specify capture requirements (resolution, overlap, sensor type), and we'll handle pilot assignment and scheduling.

Example: Get Campaigns

GET /api/v1/campaigns
Authorization: Bearer YOUR_TOKEN

# Response
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "type": "campaign",
      "attributes": {
        "name": "Site Inspection Q1",
        "aasmState": "active",
        "dueAt": "2024-04-15",
        ...
      }
    }
  ]
}

Recurring Schedules

Automated periodic flights (weekly, monthly, quarterly) for ongoing monitoring. Recurring campaigns automatically generate new missions on your specified schedule, keeping your data fresh without manual intervention.

Campaign Status

Track the status of your campaigns in real-time via the show endpoint. Campaign states include:

pending — Awaiting pilot assignment
active — Missions are in progress
completed — All missions finished, data delivered
archived — Campaign closed

Example: Get Campaign Details

GET /api/v1/campaigns/:id
Authorization: Bearer YOUR_TOKEN

See the full Campaigns API reference.

Artifacts & Raw Imagery

Artifacts are the individual pieces of data captured during missions — typically drone photographs with embedded GPS and EXIF metadata. Use the artifacts endpoint to retrieve imagery for your account, filtered by campaign or file type.

Example: List Artifacts

GET /api/v1/artifacts?campaign_id=a1b2c3d4-...
Authorization: Bearer YOUR_TOKEN

# Response includes image URLs, GPS coordinates,
# camera metadata, and thumbnails for each artifact.

See the full Artifacts API reference.

Processed Outputs

Beyond raw imagery, Raad processes your data into higher-order deliverables. These are available as artifacts or downloadable files once processing completes.

Orthomosaics

Georeferenced 2D maps stitched from overlapping images. Orthomosaics provide a seamless, geometrically-corrected aerial view of your site suitable for measurement and analysis.

3D Models

Textured mesh models generated from overlapping imagery. Useful for volumetric analysis, visual inspection, and stakeholder presentations. Available in OBJ and glTF formats.

Point Clouds

Dense 3D point cloud data in LAS/LAZ format. Point clouds enable precise measurements, terrain analysis, and integration with CAD/GIS tools.

Webhooks

Set up webhooks to receive real-time notifications when events occur in your account:

Mission status changes
Processing completion
Image classifier results
Anomaly detection alerts

Webhook support is coming soon. Check back for updates.

Image Classifiers

Run pre-built classifiers on your imagery for automated analysis — object detection, damage assessment, vegetation health, and more.

Image classifier API is coming soon.

Running AI Models

Execute custom AI models on your image sets:

Object Detection — Identify vehicles, equipment, structures
Change Detection — Compare imagery across time periods
Damage Assessment — Roof condition, structural issues
Vegetation Analysis — NDVI, crop health, tree inventory
Custom Models — Run your own trained models on our infrastructure

AI model execution API is coming soon.

Next Steps

Ready to start building? Here's what to do next:

Authentication — Get your JWT token
Sites — Create and manage your locations
Campaigns — Request aerial data collection
Artifacts — Retrieve captured imagery
API Reference — Explore all endpoints