DOCSEARCHbyAlgolia
Submit Docs

OpenSolar API Documentation

website·Indexed 31 days ago

https://developers-dev.sunsuite.com.au

Developer documentation for the OpenSolar API, providing endpoints and guides for managing solar projects, contacts, proposals, and system designs. Includes detailed specifications for webhooks (Project, Contact, Quote, Event), bearer token authentication, private file management, and organizational connection requests.

Tokens
29.3K
Snippets
141
Records
211
Agent score
47%

What's inside OpenSolar

  1. Overview of OpenSolar Model Context Protocol (MCP)

    OpenSolar MCP (Model Context Protocol) allows AI agents and MCP hosts to securely call OpenSolar tools on behalf of an organization. This enables agents to perform tasks such as listing projects, updating contacts, running auto-designs, and configuring webhooks without requiring custom API clients. MCP is complementary to the OpenSolar REST API: use the REST API for standard application integrations and MCP for AI assistants operating via a governed tool allowlist.

  2. Overview of OpenSolar MCP

    OpenSolar MCP is a remote Model Context Protocol server that enables AI agents to execute OpenSolar tools on behalf of an organization. It allows agents to perform tasks such as listing projects, updating contacts, running auto-design, and configuring webhooks without requiring the developer to write custom API clients.

  3. Embed AI-powered solar designs using the OpenSolar SDK

    The OpenSolar Software Development Kit (SDK) allows large companies with sophisticated workflows to embed AI-powered solar design capabilities directly into their own applications, reducing the need for custom development to deliver design functionality.

  4. Quote webhook payload reference

    The Quote webhook payload provides comprehensive details about a supplier quote, including pricing, line items, delivery information, and associated contacts. The payload is structured with a top-level event wrapper and a fields object containing the quote data.
    {
  "id": "integer (Quote ID)",
  "address": "string (Delivery address)",
  "zip": "string (Postal/ZIP code)",
  "state": "string (State or region)",
  "locality": "string (City or suburb)",
  "county": "string | null",
  "country": "string (ISO 3166-1 alpha-2 code)",
  "created_date": "datetime",
  "modified_date": "datetime",
  "status": "string (e.g., under_review, awaiting_order, ordered)",
  "quote_valid_until": "date | null",
  "estimated_delivery_date": "date | null",
  "notes": "string",
  "org_name": "string (Organization owning the quote)",
  "supplier_name": "string (Supplier organization)",
  "project_id": "integer | null",
  "pro_contact": "object | null (Contact of the pro user)",
  "account_manager_data": "array (Assigned account managers)",
  "data": "object (Line items keyed by index)",
  "custom_data": "object | null",
  "cost_summary": "object (subtotal, discount, shipping, tax, total)",
  "files": "array (Attached files with file_name and file_url)"
}

  5. Understand OpenSolar API throttling types

    OpenSolar employs two distinct types of throttling to maintain performance and prevent misuse:

    • Throttling per User: Limits are applied to the individual user making the request.
    • Throttling per Org: Limits are shared across all users within a specific organization.

  6. Integrate OpenSolar SDK for 3D solar design and modeling

    The OpenSolar SDK allows partners to integrate OpenSolar platform functionality into their own applications. Key capabilities include 3D project design and modeling, viewing shade projections, and accessing solar radiance data. Integration is primarily handled via the @opensolar/ossdk-react library. Note that the SDK is a paid service requiring a commercial agreement with OpenSolar.
    npm install @opensolar/ossdk-react

  7. Understand the Contact webhook payload structure

    The Contact webhook payload provides details about contacts associated with a project. It includes metadata about the event (timestamp, model, event type) and a fields object containing the contact's profile information, including their name, email, phone, and related API endpoints for their organization, projects, and user account.
    {
  "timestamp": "1605832666",
  "model": "Contact",
  "model_id": 5,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "display": "george costanza",
    "email": "george@vanderlayindustries.com",
    "family_name": "costanza",
    "first_name": "george",
    "id": 5,
    "org": "/api/orgs/14/",
    "phone": "99991234",
    "projects": ["/api/orgs/14/projects/10/"],
    "url": "/api/orgs/14/contacts/5/",
    "user": "/auth/users/6/"
  }
}

  8. Understand the Webhooks Event payload structure

    When a webhook event is triggered for a project, the system sends an Event payload. This payload includes metadata about the event (timestamp, model, identifier, and event type) and a fields object containing the specific data associated with the event, such as project details, dates, and user information.
    {
  "timestamp": "1605832669",
  "model": "Event",
  "model_id": 5,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "action": "/api/orgs/27/actions/1/",
    "archive_for": null,
    "completion_date": "2020-01-01T12:00:00.000000Z",
    "contact": "/api/orgs/15/contacts/6/",
    "created_date": "2020-01-02T12:00:00.000000Z",
    "duration": 0,
    "end": null,
    "event_type_id": 29,
    "id": 5,
    "is_archived": false,
    "is_complete": true,
    "location_override": "",
    "modified_date": "2020-01-01T12:00:00.000000Z",
    "notes": null,
    "org": "/api/orgs/15/",
    "project": "/api/orgs/15/projects/11/",
    "project_name": "Vandelay Industries",
    "repeat": 0,
    "start": null,
    "task_status": 0,
    "team_members": [],
    "title": "Design Systems",
    "url": "/api/orgs/15/events/5/",
    "user": "/auth/users/7/",
    "who": {
      "display": "george costanza",
      "email": "george@vanderlayindustries.com",
      "portrait_image_public_url": null
    }
  }
}

  9. Understand Project webhook payload constraints

    The Project webhook payload provides details about the state of a project. Users should be aware of two primary constraints:

    1. Private File Expiration: The file_contents URL used for downloading private files is time-delimited and expires after 1 hour.
    2. API Plan Restrictions: The design field (containing compressed design data) is only included in the payload for organizations on the Raw Data API Access plan.

  10. Monitor and manage MCP budget

    To check current organisation limits and remaining budget:

    1. In the OpenSolar app, navigate to Control → Integrations → MCP.
    2. For a detailed overview, go to Control → Integrations → MCP → Overview.
    3. Alternatively, ask the agent to read opensolar://docs/throttles.

  11. Use Model Context Protocol (MCP) for AI-powered OpenSolar workflows

    OpenSolar supports the Model Context Protocol (MCP), allowing AI agents to securely access OpenSolar tools. This enables AI agents to interact with projects, customers, designs, and webhooks without the need for developers to build or maintain custom API integrations.

  12. Manage private files using the Private Files API

    The Private Files API provides endpoints to list, create, retrieve, update, and delete private files for an organization. Access is restricted to authenticated users with a 'Pro' role for the organization. The API is throttled to 1,000 requests per day per organization for both read and write operations.

    Endpoints

    MethodEndpointDescription
    GET/api/orgs/:org_id/private_files/List private files
    GET/api/orgs/:org_id/private_files/:file_id/Retrieve a private file
    POST/api/orgs/:org_id/private_files/Create a private file
    PATCH/api/orgs/:org_id/private_files/:file_id/Update a private file
    DELETE/api/orgs/:org_id/private_files/:file_id/Delete a private file