Objects and Relationships

The Alentis API is built around three main object types: Sites, Portfolios, and Documents. Understanding how these objects relate to each other is essential for working with the API effectively.

Core Objects

Sites

A Site represents a physical site. Anything that has more than one solar panel can be classified as a site. Each site belongs to an organisation and can optionally be assigned to a portfolio.

Key Properties:

id - Unique identifier (UUID)
siteName - Name of the site
address - Physical address
capacity - Installation capacity (e.g., 1000)
unit - Capacity unit (e.g., "kW", "MW")
latitude / longitude - Geographic coordinates
portfolioId - Reference to the portfolio (optional)
siteManager - Assigned site manager (optional)
coverImageUrl - Cover image for the site (optional)

Relationships:

Belongs to one Organisation
Can belong to one Portfolio (optional)
Can have one Site Manager (optional)
Can have multiple Documents

Portfolios

A Portfolio is a collection of sites, used for grouping and organizing multiple solar installations.

Key Properties:

id - Unique identifier (UUID)
name - Portfolio name
organisationId - Organisation that owns the portfolio

Relationships:

Belongs to one Organisation
Contains multiple Sites (one-to-many)

Documents

Documents are files associated with sites, such as reports, images, or other documentation. Documents are stored securely and can be accessed via temporary signed URLs.

Key Properties:

id - Unique identifier (UUID)
siteId - Reference to the site (required for most document types)
type - Document type (e.g., "coverImage", "report", "om-documents", "documents")
filename - Original filename
path - Storage path (internal)
status - Upload status (pending, uploaded, failed, approved, completed)
mimeType - MIME type of the file (e.g., "application/pdf", "image/jpeg")
sizeBytes - File size in bytes
uploadedBy - User ID who uploaded the document
createdAt - Timestamp when document was created

Relationships:

Belongs to one Site (many-to-one) - Documents are always associated with a specific site
Belongs to one Organisation - Documents inherit organisation access from their site
Can be associated with O&M records (for om-documents type)

Relationship Diagram

Organisation
    │
    ├─── Portfolio 1
    │       ├─── Site A
    │       │       ├─── Document 1 (coverImage)
    │       │       └─── Document 2 (report)
    │       └─── Site B
    │               └─── Document 3 (coverImage)
    │
    ├─── Portfolio 2
    │       └─── Site C
    │
    └─── Site D (no portfolio)
            └─── Document 4 (report)

Common Workflows

1. Creating a Site in a Portfolio

# First, get portfolio ID
curl -H "x-api-key: your-key" \
  https://app.alentisenergy.com/api/portfolios

# Create site and assign to portfolio
curl -X POST \
  -H "x-api-key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "siteName": "Solar Farm Alpha",
    "capacity": 1000,
    "unit": "kW",
    "portfolioId": "portfolio-uuid-here"
  }' \
  https://app.alentisenergy.com/api/sites

2. Getting All Sites in a Portfolio

# Get portfolios with their sites
curl -H "x-api-key: your-key" \
  https://app.alentisenergy.com/api/portfolios/with-sites

# Then filter sites by portfolioId
curl -H "x-api-key: your-key" \
  "https://app.alentisenergy.com/api/sites?portfolioId=portfolio-uuid-here"

3. Moving a Site Between Portfolios

# Update site's portfolioId
curl -X PUT \
  -H "x-api-key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"portfolioId": "new-portfolio-uuid"}' \
  https://app.alentisenergy.com/api/sites/site-uuid-here

4. Removing a Site from a Portfolio

# Set portfolioId to null
curl -X PUT \
  -H "x-api-key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"portfolioId": null}' \
  https://app.alentisenergy.com/api/sites/site-uuid-here

5. Uploading Documents

# Upload multiple documents to a site
# This generates signed upload URLs for each file
curl -X POST \
  -H "x-api-key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "site-uuid-here",
    "fileType": "documents",
    "files": [
      {
        "filename": "ppa_agreement.pdf",
        "mimeType": "application/pdf",
        "fileSize": 1048576,
        "documentType": "ppa"
      },
      {
        "filename": "mcs_certificate.pdf",
        "mimeType": "application/pdf",
        "fileSize": 512000,
        "documentType": "mcs_certificate"
      }
    ]
  }' \
  https://app.alentisenergy.com/api/docs/bulk-upload-url

# Response includes upload URLs for each file
# Each URL is valid for 60 seconds
# After uploading, use the returned documentId to reference the document

Data Hierarchy

The data follows this hierarchy:

Organisation (top level)
- Contains multiple Portfolios
- Contains multiple Sites (directly or via portfolios)
- All Documents belong to sites within the organisation
Portfolio (optional grouping)
- Contains multiple Sites
- Sites can be moved between portfolios or removed from portfolios
Site (core entity)
- Belongs to an Organisation
- Optionally belongs to a Portfolio
- Can have multiple Documents
- Can have one Site Manager
Document (file attachment)
- Always belongs to one Site
- Always belongs to one Organisation (via site)
- Has a type (e.g., coverImage, report, om-documents, documents). This isn't mandatory, however this is useful for search functionalities and populating the site where we can extract key pieces of information if we know the document type.
- Can be uploaded via the bulk upload endpoint which generates temporary signed URLs (valid for 60 seconds)
- Documents are stored securely and access is controlled by organisation membership

Important Notes

Sites can exist without portfolios: A site doesn't require a portfolio assignment
One site, one portfolio: A site can only belong to one portfolio at a time
Documents are site-specific: Documents are always associated with a specific site
Organisation isolation: All objects are scoped to your organisation - you can only access objects belonging to your organisation
Document upload: Documents are uploaded via the bulk upload endpoint which generates temporary signed URLs
Temporary URLs: Upload URLs are signed and expire after 60 seconds for security
Document types: When uploading, specify document types such as ppa, mcs_certificate, string_layout, om_ticket, invoice, equipment_register, warranty_information, handover_document, ppm, epc, finance_agreements, insurance, land_lease, om_contract, spare_parts, or other
File types: The fileType parameter can be documents (regular site documents), om-documents (O&M documents requiring omRecordId), or coverImage (site cover images)
Organisation isolation: All documents are scoped to your organisation - you can only upload documents to sites belonging to your organisation

API Endpoints by Object

Sites

GET /api/sites - List all sites (optionally filter by siteId)
POST /api/sites - Create a new site
PUT /api/sites/:id - Update a site
DELETE /api/sites/:id - Delete a site

Portfolios

GET /api/portfolios - List all portfolios
GET /api/portfolios/with-sites - List portfolios with their sites
POST /api/portfolios - Create portfolios (bulk)
PUT /api/portfolios/:id - Update a portfolio
DELETE /api/portfolios/:id - Delete a portfolio
POST /api/portfolios/:id/sites - Add sites to portfolio
DELETE /api/portfolios/:id/sites - Remove site from portfolio

Documents

POST /api/docs/bulk-upload-url - Generate multiple signed upload URLs for bulk file uploads (public API)
Documents are created via the bulk upload endpoint
Each file can specify a document type for proper categorization
Upload URLs are temporary and expire after 60 seconds
Maximum 20 files per bulk upload request

Document Upload Flow:

Prepare file metadata - Collect filenames, MIME types, and document types for each file
Request upload URLs - Call the bulk upload endpoint to get signed upload URLs
Upload files - Use each signed URL to upload the actual file (URL expires in 60 seconds)
Store document IDs - Save the returned document IDs for future reference

# Step 1: Request upload URLs for multiple files
curl -X POST \
  -H "x-api-key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "site-uuid-here",
    "fileType": "documents",
    "files": [
      {
        "filename": "report.pdf",
        "mimeType": "application/pdf",
        "documentType": "ppa"
      }
    ]
  }' \
  https://app.alentisenergy.com/api/docs/bulk-upload-url

# Response includes upload URLs and document IDs:
# {
#   "results": [
#     {
#       "filename": "report.pdf",
#       "success": true,
#       "uploadUrl": { "path": "...", "token": "..." },
#       "documentId": "document-uuid-here"
#     }
#   ],
#   "summary": { "total": 1, "successful": 1, "failed": 0 }
# }

# Step 2: Upload the file using the signed URL
# Use the uploadUrl.path and uploadUrl.token to upload the file

Core Objects​

Sites​

Portfolios​

Documents​

Relationship Diagram​

Common Workflows​

1. Creating a Site in a Portfolio​

2. Getting All Sites in a Portfolio​

3. Moving a Site Between Portfolios​

4. Removing a Site from a Portfolio​

5. Uploading Documents​

Data Hierarchy​

Important Notes​

API Endpoints by Object​

Sites​

Portfolios​

Documents​

Core Objects

Sites

Portfolios

Documents

Relationship Diagram

Common Workflows

1. Creating a Site in a Portfolio

2. Getting All Sites in a Portfolio

3. Moving a Site Between Portfolios

4. Removing a Site from a Portfolio

5. Uploading Documents

Data Hierarchy

Important Notes

API Endpoints by Object

Sites

Portfolios

Documents