# API Specification

Overra exposes a local communication interface between the dashboard and the local agent.

**This API allows:**

* Authorization submission
* State queries
* Audit log retrieval
* Authority information inspection

The API is local-first and does not expose public internet endpoints. All state-changing operations require valid cryptographic authorization.

***

### Design Principles

**The Overra API is designed to:**

* Be minimal
* Expose only necessary functionality
* Require signature verification for state mutation
* Maintain strict trust boundaries

**The API does not allow:**

* Arbitrary command execution
* Remote shell access
* Runtime policy modification
* Unauthenticated state mutation

***

## Base Endpoint

**The local agent typically binds to:**

Port configuration is defined during installation.

The agent should not expose public network interfaces by default.

***

## 1. Get System Status

#### Endpoint

Pre /authorize

#### Description

Returns the current containment state and metadata.

#### Response

```json
{
  "state": "NORMAL" | "CONTAINED",
  "device_id": "uuid",
  "registered_wallet": "public_key",
  "agent_version": "x.x.x",
  "last_authorization": 1712345678
}
```

## 2. Submit Authorization Request

#### Endpoint

Post /authorize

#### Description

Submits a signed authorization payload for verification.

#### Request Body

```
{
  "payload": {
    "action": "containment" | "release",
    "device_id": "uuid",
    "nonce": "unique_string",
    "timestamp": 1712345678,
    "expires": 60
  },
  "signature": "base64_signature",
  "public_key": "base64_public_key"
}
```

#### Response (Success)

```
{
  "status": "approved",
  "new_state": "CONTAINED"
}
```

#### Response (Failure)

```
{
  "status": "rejected",
  "reason": "invalid_signature | nonce_used | expired | authority_mismatch"
}
```

The agent performs full verification before returning approval.

State mutation occurs only after successful verification.

***

## 3. Get Audit Logs

#### Endpoint

```
GET /logs
```

#### Optional Query Parameters

```c++
?limit=50
?type=authorization
```

#### Response

```cpp
[
  {
    "timestamp": 1712345678,
    "event": "authorization_request",
    "result": "approved",
    "action": "containment"
  }
]
```

Logs are append-only.

The API does not support deletion.

***

## 4. Get Authority Information

#### Endpoint

```
GET /authority
```

#### Response

```cpp
{
  "registered_wallet": "public_key",
  "date_registered": 1712000000,
  "last_verified": 1712345678
}
```

This endpoint is read-only.

***

## 5. Update Authority

#### Endpoint

```
POST /authority/update
```

Requires a valid signed authorization from the current authority.

Payload structure mirrors standard authorization request format.

Authority update cannot occur without valid signature.

***

## Security Controls

The API enforces:

* Signature validation
* Authority binding
* Nonce replay protection
* Expiration window validation
* Strict schema enforcement

Unsigned or malformed requests are rejected immediately.

***

## Deployment Considerations

Production deployments should ensure:

* Local-only binding (127.0.0.1)
* Firewall restrictions
* Restricted OS-level permissions
* Secure storage of nonce and state data

The API is designed for local interaction and integration into trusted execution environments.

***

## API Summary

The Overra API provides a minimal, deterministic interface between:

User interaction layer\
and\
Enforcement boundary

All state mutation is:

* Cryptographically authorized
* Locally verified
* Deterministically executed
* Transparently logged

No endpoint allows discretionary or unauthenticated state control.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://overra.gitbook.io/overra-docs/usage/api-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.