AMPECO Public API Integration Guide

AMPECO Public API Integration Guide

Explore and integrate with the AMPECO EV Charging Platform Public API.

---

IMPORTANT: Update Reference Docs First

Before using the reference documentation, ensure you have the latest API spec:

bash scripts/​fetch-and-generate.sh

This fetches the latest OpenAPI spec from https://developers.ampeco.com/openapi/ and regenerates all reference files.

Prerequisites: curl and jq must be installed:

• macOS: brew install jq
• Ubuntu/​Debian: apt-get install jq

---

Getting Started

1. Get API Access

Contact your AMPECO Customer Success Manager or generate a token in: Back Office → API Access Tokens

2. Base URL

https://{tenantUrl}/​public-api/

Replace {tenantUrl} with your organization's tenant URL.

3. Authentication

curl -H "Authorization: Bearer {your-api-token}" \
     https://{tenantUrl}/​public-api/​resources/​charge-points/​v2.0/

---

Quick Reference

Response Format: JSON with data wrapper

{
  "data": [...],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 100, "total": 250 }
}

Path Patterns:

• Resources: /​public-api/​resources/​{resource-name}/​v{X.Y}/
• Actions: /​public-api/​actions/​{target}/​v{X.Y}/​{id}/​{action}
• Notifications: /​public-api/​notifications/​v{X.Y}/

---

<!-- BEGIN:QUICK_INDEX -->

Endpoint Quick Index

Run bash scripts/​fetch-and-generate.sh to update this index

Actions: See reference/​endpoints-index.md for charge point, user, reservation, and notification actions.

<!-- END:QUICK_INDEX -->

---

Data Model Overview

Understanding how AMPECO entities relate helps you choose the right endpoints.

Operator (tenant scope)
├── Location → ChargePoint → EVSE → Session
├── User → Session, PartnerInvite
├── Partner → ChargePoint (owned), PartnerInvite (users)
└── Tariff, SubscriptionPlan

Common Use Cases:

See reference/​data-model.md for detailed relationships and recipes.

---

Common Patterns

Pagination

Cursor pagination (default, recommended):

GET /​public-api/​resources/​users/​v1.0?per_page=25
GET /​public-api/​resources/​users/​v1.0?cursor={next_cursor}&per_page=25

Page pagination (legacy support):

GET /​public-api/​resources/​users/​v1.0?page=1&per_page=25

Filtering

Use filter[fieldName]=value format:

GET /​public-api/​resources/​sessions/​v1.0?filter[userId]=123
GET /​public-api/​resources/​sessions/​v1.0?filter[status]=active
GET /​public-api/​resources/​sessions/​v1.0?filter[startedAfter]=2024-01-01T00:00:00Z

Includes

Embed related resources with include[]=relationName:

GET /​public-api/​resources/​charge-points/​v1.0?include[]=evses&include[]=location

Error Responses

{
  "message": "Unauthenticated."
}

Status codes: 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error)

---

How to Use This Skill

1. First: Run bash scripts/​fetch-and-generate.sh to get latest docs
2. Find endpoints: Load reference/​endpoints-index.md
3. Check schemas: Load reference/​schemas-index.md
4. Check patterns: Load reference/​common-patterns.md for pagination, filtering, errors
5. See deprecated: Load reference/​deprecation-map.md

Reference Files

• reference/​data-model.md - Entity relationships and use case recipes
• reference/​endpoints-index.md - Complete list of all endpoints
• reference/​schemas-index.md - Schema summaries
• reference/​deprecation-map.md - Deprecated endpoints
• reference/​common-patterns.md - Pagination, filtering, errors

Live Documentation

https://developers.ampeco.com