# Welcome to the Optimiciti Developer Portal

The developer portal is your starting point for accessing our public-facing API. This portal is for developers and users who want to integrate Optimiciti's optimization solvers directly into their own applications and workflows by making requests to our back-end.

[Click here](https://optimiciti.com) to visit our main site, where you can solve problems interactively in your browser without writing any code.

Our [API Reference](/api) has the most up-to-date endpoint documentation.

---

## What is the Optimiciti API?

The Optimiciti API gives you programmatic access to the same optimization engine that powers our web application.

Submit a problem, receive a `problemId`, then poll for results — all over standard HTTPS requests authenticated with your API key.

---

## Optimization Models

The API currently supports two problem types, specified via the `problemType` field in your request body.

### Vehicle Routing (`vehicle-routing`)

The classic Vehicle Routing Problem (VRP). One or more vehicles depart from a depot and must visit a set of locations using the lowest-cost routes. Supports:

- **Capacity constraints** — assign demand values to locations and enforce vehicle load limits
- **Time windows** — restrict arrival times at individual locations
- **Multiple vehicle types** — model fleets with different capacities, speeds, or cost profiles
- **Automatic travel time calculation** — travel times and distances are calculated automatically from your location coordinates

### Pickup & Delivery Routing (`pickup-delivery`)

An extension of the VRP where locations are paired into *trips*. Each trip has a pickup location that must be visited **before** its corresponding delivery location, and both stops must be served by the **same vehicle**. Useful for:

- Ride-hailing and shuttle services
- Courier and last-mile delivery with paired collections
- Airport and logistics transfer networks

---

## API Workflow

Optimization runs are **asynchronous**. The typical flow is:

<Stepper>

1. **Submit a problem**

   `POST /problem` with your `UserId` and a `Problem` object containing the `problemType`, locations, vehicles, vehicle types, and (optionally) travel costs and time settings. The response returns a `problemId`.

   ```json
   {
     "UserId": "your-user-id",
     "Problem": {
       "problemType": "vehicle-routing",
       "ProblemData": {
         "Locations": [...],
         "Vehicles": [...],
         "VehicleTypes": [...],
         "TravelCosts": [...]
       }
     }
   }
   ```

1. **Poll for results**

   `GET /problem/{problemId}` returns the current status of the run. When the optimization is complete, the response includes the full results object containing the assigned routes and any unassigned locations.

1. **Cancel if needed**

   `POST /problem/cancel/{problemId}` cancels an in-progress run. This has no effect if the run has already completed.

</Stepper>

---

## Additional Endpoints

| Endpoint | Description |
|---|---|
| `POST /cost_matrix` | Calculate a travel time and distance matrix for a set of locations |
| `GET /health` | Returns the operational status of the API |

---

## Plans & Limits

Access to the API is tied to your subscription plan. The following limits apply to each optimization run.

| | **Starter** | **Professional** |
|---|---|---|
| **Price** | Free | $20 / month |
| **Locations per run** | 50 | 250 |
| **Trips per run** | — | 250 |
| **Vehicles per run** | — | 50 |
| **Vehicle types per run** | — | 20 |
| **Saved scenarios** | 5 | Unlimited |
| **API access** | — | — |
| **Auto-populate travel times** | — | ✓ |

:::tip

**Developer plan coming soon.** A dedicated Developer plan will offer bigger limits on problem size, up to 10 API solves per minute, and full REST API access. [Join the waitlist](https://optimiciti.com/pricing) to be notified at launch.

:::

---

## Authentication

All API requests must include a valid API key in the `Authorization` header:

```http
Authorization: Bearer <your-api-key>
```

You can generate and manage your API keys from your account page after logging in. API keys are scoped to your user account and subject to the rate limits of your plan.

---

## Rate Limits

Rate limits vary by endpoint and subscription plan. Write endpoints (submitting and cancelling problems) are more restricted than read endpoints.

Requests that exceed your rate limit will receive a `429 Too Many Requests` response. Contact [api@optimiciti.com](mailto:api@optimiciti.com) if you need higher limits for your use case.

---

## Contact

Questions about the API or your subscription? Reach us at [api@optimiciti.com](mailto:api@optimiciti.com) or visit the [terms of service](https://optimiciti.com/terms-of-use).