> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Overview

> Unified optimization platform providing powerful solvers for routing, scheduling, and resource allocation challenges

## Welcome to Solvice

The Solvice Platform provides enterprise-grade optimization solvers through a simple REST API. Submit a problem, get back an optimized solution — with full explanations of every decision the solver made.

<CardGroup cols={2}>
  <Card title="VRP Solver" icon="route" href="/guides/vrp/overview">
    Vehicle routing and fleet optimization with real-world constraints
  </Card>

  <Card title="CLUST Solver" icon="map-location-dot" href="mailto:support@solvice.io?subject=Clustering%20API%20Documentation">
    Geographic clustering for territory and zone management
  </Card>
</CardGroup>

***

## Getting Started

<Steps>
  <Step title="Create your account">
    Visit [platform.solvice.io](https://platform.solvice.io) and sign up with your email or SSO provider.

    <Note>
      New accounts include a 14-day free trial with full access to all solver capabilities.
    </Note>
  </Step>

  <Step title="Create an API key">
    Navigate to **Settings** → **API Keys** and click **Create API Key**.

    <Warning>
      Copy your API key immediately after creation. For security reasons, you won't be able to view the full key again.
    </Warning>
  </Step>

  <Step title="Solve a demo problem">
    With your API key ready, fetch a demo VRP problem and solve it in one go:

    ```bash theme={null}
    curl https://api.solvice.io/v2/vrp/demo -H "Authorization: YOUR_API_KEY" | \
    curl https://api.solvice.io/v2/vrp/solve -X POST \
         -H "Authorization: YOUR_API_KEY" \
         -H "Content-Type: application/json" -d @-
    ```

    <Check>
      The API returns a job ID. Your job appears in the dashboard **Jobs** section within seconds.
    </Check>
  </Step>

  <Step title="Retrieve the solution">
    Poll for status, then fetch the result:

    ```bash theme={null}
    curl 'https://api.solvice.io/v2/vrp/jobs/{jobId}/status' \
      -H 'Authorization: YOUR_API_KEY'

    curl 'https://api.solvice.io/v2/vrp/jobs/{jobId}/solution' \
      -H 'Authorization: YOUR_API_KEY'
    ```
  </Step>
</Steps>

***

## How It Works

Every solver follows the same four-step pattern: submit, monitor, retrieve, understand.

<Steps>
  <Step title="Submit optimization request">
    Send your problem data to the appropriate solver endpoint. The API immediately returns a job ID for tracking.

    ```
    POST /v2/{solver}/solve
    ```
  </Step>

  <Step title="Monitor job progress">
    Poll the status endpoint to track optimization progress. Jobs transition through states: `QUEUED` → `SOLVING` → `SOLVED`.

    ```
    GET /v2/{solver}/jobs/{jobId}/status
    ```
  </Step>

  <Step title="Retrieve optimized solution">
    Once solved, fetch your optimized solution with detailed assignments and metrics.

    ```
    GET /v2/{solver}/jobs/{jobId}/solution
    ```
  </Step>

  <Step title="Understand decisions">
    Get explanations for constraint violations and optimization trade-offs.

    ```
    GET /v2/{solver}/jobs/{jobId}/explanation
    ```
  </Step>
</Steps>

***

## Unified API Design

Every Solvice solver follows consistent REST patterns, making integration straightforward across your entire optimization stack.

<Tabs>
  <Tab title="Action Endpoints">
    #### Solve

    Submit optimization requests for processing. This is the primary endpoint for all solvers.

    <ParamField body="request" type="object" required>
      Solver-specific request object containing your problem definition
    </ParamField>

    <ResponseField name="jobId" type="string" required>
      Unique identifier for tracking your optimization job
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Initial job status (typically `QUEUED`)
    </ResponseField>

    #### Evaluate

    Assess the quality of existing solutions without optimization.

    <Info>
      Available for VRP solver only
    </Info>

    #### Suggest

    Get intelligent suggestions for single assignment improvements.

    <Info>
      Available for VRP solver only
    </Info>
  </Tab>

  <Tab title="Information Endpoints">
    #### Job Status

    Monitor the current state of your optimization job.

    <ResponseField name="status" type="string" required>
      Current job state: `QUEUED`, `SOLVING`, `SOLVED`, or `ERROR`
    </ResponseField>

    <ResponseField name="progress" type="number">
      Optimization progress percentage (0-100)
    </ResponseField>

    #### Solution

    Retrieve the optimized solution once processing completes.

    <Check>
      Only available when job status is `SOLVED`
    </Check>

    #### Explanation

    Understand constraint violations and optimization decisions.

    <ResponseField name="violations" type="array" required>
      List of constraint violations with involved entities
    </ResponseField>

    <ResponseField name="score" type="object" required>
      Detailed breakdown of hard and soft constraint scores
    </ResponseField>
  </Tab>
</Tabs>

### Authentication

All API requests require an API key in the `Authorization` header. See the [authentication guide](/guides/platform/authentication) for setup and security best practices.

***

## Asynchronous Processing

Optimization problems can take seconds to minutes depending on complexity. Asynchronous processing keeps your application responsive while the solver works.

<AccordionGroup>
  <Accordion title="Polling example">
    ```javascript theme={null}
    async function waitForSolution(jobId) {
      const maxAttempts = 60;
      const pollInterval = 5000; // 5 seconds

      for (let i = 0; i < maxAttempts; i++) {
        const status = await checkJobStatus(jobId);

        if (status === 'SOLVED') {
          return await fetchSolution(jobId);
        } else if (status === 'ERROR') {
          throw new Error('Optimization failed');
        }

        await sleep(pollInterval);
      }

      throw new Error('Optimization timeout');
    }
    ```
  </Accordion>

  <Accordion title="Synchronous alternatives">
    For low-latency requirements, VRP solver offers synchronous endpoints:

    ```
    POST /v2/vrp/solve/sync
    POST /v2/vrp/evaluate/sync
    POST /v2/vrp/suggest/sync
    ```

    <Warning>
      Synchronous endpoints have stricter size and time limits.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Dashboard

The [Solvice Dashboard](https://platform.solvice.io) gives you real-time visibility into API keys, running jobs, solutions, and usage.

| Section      | What you'll find                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| **Jobs**     | All optimization requests with status, solver type, duration, and drill-down to solution/explanation/raw JSON |
| **API Keys** | Create, revoke, and monitor keys with per-solver permissions                                                  |
| **Usage**    | API calls, solve time, and quota tracking over time                                                           |
| **Settings** | Profile, team management, billing, and notification preferences                                               |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="VRP Quickstart" icon="route" href="/guides/vrp/quickstart">
    Solve your first routing problem
  </Card>

  <Card title="Authentication" icon="key" href="/guides/platform/authentication">
    API key setup and security best practices
  </Card>

  <Card title="SDK Libraries" icon="cube" href="/guides/platform/sdks">
    Use our SDKs for faster integration
  </Card>

  <Card title="Claude & MCP" icon="message-bot" href="/guides/platform/claude-mcp">
    Connect AI assistants to the solver
  </Card>
</CardGroup>