Skip to main content

Offerings API

The Offerings API allows you to manage offerings (products/services) in your workspace. Offerings represent your own products/services that you want to compare against competitors, as well as competitor offerings discovered during research.

List Offerings​

Get all offerings for your workspace (both your organization's offerings and competitor offerings).

GET /api/offerings

Response​

{
  "offerings": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "name": "My Offering",
      "description": "Offering description",
      "audience": "Primary buyer persona",
      "valueProps": ["Value prop 1", "Value prop 2"],
      "features": [
        {
          "id": "feature-id",
          "name": "Feature Name",
          "description": "Feature description"
        }
      ],
      "capabilityIds": ["capability-id-1"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "createdByUserId": "user-id",
      "isActive": true
    }
  ]
}

Get Offering​

Get a specific offering by ID.

GET /api/offerings/{id}

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "offering": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "My Offering",
    "description": "Offering description",
    "audience": "Primary buyer persona",
    "valueProps": ["Value prop 1"],
    "features": [],
    "capabilityIds": ["capability-id-1"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id",
    "isActive": true
  }
}

Create Offering​

Create a new offering. Requires EDITOR role or higher.

POST /api/offerings

Request Body​

{
  "name": "My Offering",
  "description": "Offering description",
  "audience": "Primary buyer persona",
  "valueProps": ["Value prop 1", "Value prop 2"],
  "features": [
    {
      "name": "Feature Name",
      "description": "Feature description"
    }
  ],
  "capabilityIds": ["capability-id-1"]
}

Required Fields​

  • name (string) - Offering name
  • description (string) - Offering description
  • audience (string) - Primary buyer persona

Optional Fields​

  • valueProps (array of strings) - Value propositions
  • features (array of objects) - Offering features (each with name and description)
  • capabilityIds (array of strings) - Capability IDs this offering implements
  • childOfferingIds (array of strings) - Child offering IDs for bundle/suite hierarchy

Response​

{
  "offering": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "My Offering",
    "description": "Offering description",
    "audience": "Primary buyer persona",
    "valueProps": ["Value prop 1"],
    "features": [],
    "capabilityIds": ["capability-id-1"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id",
    "isActive": true
  }
}

Update Offering​

Update an offering. Requires EDITOR role or higher.

PATCH /api/offerings/{id}

Path Parameters​

  • id (string, required) - Offering ID

Request Body​

All fields are optional. Only include fields you want to update:

{
  "name": "Updated Offering Name",
  "description": "Updated description",
  "audience": "Updated audience",
  "valueProps": ["New value prop"],
  "features": [],
  "capabilityIds": ["capability-id-1"],
  "isActive": true
}

Response​

{
  "offering": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "Updated Offering Name",
    "description": "Updated description",
    "audience": "Updated audience",
    "valueProps": ["New value prop"],
    "features": [],
    "capabilityIds": ["capability-id-1"],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id",
    "isActive": true
  }
}

Delete Offering​

Delete an offering. Requires EDITOR role or higher.

DELETE /api/offerings/{id}

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "success": true
}

Discover Offerings​

Discover offerings from a competitor website. Triggers an analysis job.

POST /api/offerings/discover

Request Body​

{
  "websiteUrl": "https://competitor.com",
  "competitorId": "competitor-id"
}

Required Fields​

  • websiteUrl (string) - Competitor website URL
  • competitorId (string) - Competitor ID

Response​

{
  "jobId": "job-id-for-tracking-discovery"
}

Enrich Offering​

Trigger enrichment analysis for an offering.

POST /api/offerings/enrich

Request Body​

{
  "offeringIds": ["offering-id-1", "offering-id-2"]
}

Required Fields​

  • offeringIds (array of strings) - Offering IDs to enrich

Response​

{
  "jobId": "job-id-for-tracking-enrichment"
}

Upload Offering Document​

Upload a document (PDF, DOCX, etc.) for an offering to extract features and capabilities.

POST /api/offerings/{id}/upload

Path Parameters​

  • id (string, required) - Offering ID

Request Body​

Form data with file field containing the document.

Response​

{
  "jobId": "job-id-for-tracking-extraction"
}

Reanalyze Offering​

Trigger reanalysis of an offering to update features and capabilities.

POST /api/offerings/{id}/reanalyze

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "jobId": "job-id-for-tracking-reanalysis"
}

Get Offering Knowledge Tree​

Get the knowledge tree metadata for an offering.

GET /api/offerings/{id}/knowledge-tree

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "tree": {
    "id": "tree-id",
    "treeId": "tree-id",
    "workspaceId": "workspace-id",
    "entityType": "OFFERING",
    "entityId": "offering-id",
    "version": 1,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "sources": []
  }
}

Get Offering Tree Metadata​

Get knowledge tree metadata for an offering.

GET /api/offerings/{id}/tree-metadata

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "metadata": {
    "treeId": "tree-id",
    "rootId": "root-node-id",
    "nodeCount": 10,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Delete Offering Knowledge Tree​

Delete the knowledge tree for an offering.

DELETE /api/offerings/{id}/tree

Path Parameters​

  • id (string, required) - Offering ID

Response​

{
  "success": true
}

Error Responses​

  • 400 - Bad Request (missing required fields, invalid data)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (offering doesn't exist)