Developer API Introduction

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:

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

Include the returned token in every subsequent request:

curl https://app.raad.com/api/v1/campaigns \
  -H "Authorization: Bearer <JWT_TOKEN>"

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

curl "https://app.raad.com/api/v1/sites?page=1&per_page=25" \
  -H "Authorization: Bearer <JWT_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.

curl "https://app.raad.com/api/v1/campaigns?page=1&per_page=25" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "type": "campaign",
      "attributes": {
        "name": "Site Inspection Q1",
        "state": "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

curl https://app.raad.com/api/v1/campaigns/<CAMPAIGN_ID> \
  -H "Authorization: Bearer <JWT_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.

curl "https://app.raad.com/api/v1/artifacts?campaign_id=<CAMPAIGN_ID>&file_type=JPEG" \
  -H "Authorization: Bearer <JWT_TOKEN>"

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