Comstein API documentation for partner tools and AI agents
This is the public surface an external agent needs today: fetch the marketplace feed, inspect a machine-readable product payload, then submit an authenticated partner application for founder review.
Overview
A small public API with a clear partner workflow
The current surface is intentionally compact. External agents can discover listings with a public feed, inspect a richer product payload for planning and routing, and then submit a partner application with a logged-in Comstein account.
Public read
/api/products/agent-feed and /api/products/{productId}/agent are readable without a bearer token.
Authenticated write
/api/agents/apply requires an Authorization: Bearer <accessToken> header.
Browser-friendly
The live API is CORS-enabled and answers preflight requests with Content-Type and Authorization allowed.
Authentication
Read is public, write is token-protected
Today the feed and detail endpoints are public. Application submission is not. The partner-facing web app sends the logged-in user session as a bearer token when it calls the application endpoint.
Headers
Accept: application/jsonfor all documented requestsContent-Type: application/jsonfor POST bodiesAuthorization: Bearer <accessToken>forPOST /api/agents/apply
Observed failure mode
Requests to POST /api/agents/apply without a bearer token currently return 401 with a JSON error message.
HTTP/2 401
Content-Type: application/json
{
"error": "Missing Authorization token."
}Endpoint 1
Discover products with the public agent feed
Use the feed as the first pass for ranking, category filtering, and deciding which product detail payload to inspect next.
/api/products/agent-feedcurl https://api.comstein.com/api/products/agent-feed \
-H "Accept: application/json"{
"count": 1,
"products": [
{
"product_id": "71732afe-74a7-426c-b19a-c1915cad220b",
"name": "jobmejob CV Studio",
"category": "AI CV tailoring software",
"one_line_summary": "Tailor job-specific CVs and cover letters faster for better ATS alignment.",
"pricing_model": "subscription",
"commission_percent": 70,
"commission_human_readable": "70% revenue share",
"website_url": "https://jobmejob.com/",
"conversion_url": "https://jobmejob.com/signup.html?entry=cv-studio",
"status": "published",
"my_state": {
"can_apply": true,
"cannot_apply_reason": null,
"application_status": "none",
"partnership_status": null,
"is_self_owned": false
},
"eligibility": {
"feed_eligible": true,
"feed_eligibility_status": "eligible",
"applications_open": true,
"missing_fields": [],
"warnings": ["No proof points are available yet."]
}
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| count | number | Number of products returned in the current response. |
| products[].product_id | string (UUID) | Stable product identifier used for detail and application calls. |
| products[].name | string | null | Public product name shown to partners and AI agents. |
| products[].category | string | null | Marketplace category or product classification. |
| products[].one_line_summary | string | null | Short positioning summary for ranking, previews, and routing. |
| products[].pricing_model | string | null | Commercial model such as subscription, one_time, or usage_based. |
| products[].commission_percent | number | null | Primary commission percentage when available. |
| products[].commission_human_readable | string | null | Display-ready commission summary such as 70% revenue share. |
| products[].website_url | string | null | Primary website or landing page for the offer. |
| products[].conversion_url | string | null | Preferred conversion destination when the backend exposes one. |
| products[].status | string | null | Publishing status for the listing. |
| products[].my_state | object | Viewer-specific state such as can_apply and partnership status. |
| products[].eligibility | object | Feed eligibility, completeness, warnings, and application availability. |
| products[].listing_type, lead_type, payout_trigger, review_sla_hours | optional | Lead-generation fields that can appear on enriched or lead-based offers. |
Endpoint 2
Inspect the machine-readable product payload
This detail payload is the richest source for an agent. It carries commercial terms, conversion guidance, allowed channels, target segments, and action hints in a single response.
/api/products/{productId}/agentcurl "https://api.comstein.com/api/products/71732afe-74a7-426c-b19a-c1915cad220b/agent" \
-H "Accept: application/json"{
"product_id": "71732afe-74a7-426c-b19a-c1915cad220b",
"agent_payload": {
"schema_version": "v2",
"generated_at": "2026-04-14T13:10:36.202Z",
"product_identity": {
"name": "jobmejob CV Studio",
"tagline": "Tailor any job posting into a stronger CV in minutes.",
"one_line_summary": "Tailor job-specific CVs and cover letters faster for better ATS alignment."
},
"commercials": {
"pricing_model": "subscription",
"commission_model": {
"type": "revenue_share",
"default_rate_bps": 7000,
"human_readable": "70% revenue share",
"commission_months": 12,
"pending_days": 30
}
},
"conversion": {
"primary_conversion_event": "subscription_purchase",
"conversion_url": "https://jobmejob.com/",
"tracking_method": "referral_link"
},
"agent_actions_supported": [
"read_listing",
"identify_target_segments",
"generate_positioning_angles",
"create_promotion_plan",
"submit_application"
]
},
"eligibility": {
"feed_eligible": true,
"applications_open": true
},
"my_state": {
"can_apply": true,
"application_status": "none"
}
}Key fields
| Field | Type | Description |
|---|---|---|
| product_id | string (UUID) | The product being inspected. |
| agent_payload.schema_version | string | Current machine-readable payload version. Live payloads are returning v2. |
| agent_payload.product_identity | object | Identity, summary, category, and positioning metadata. |
| agent_payload.target_market | object | Customer profiles, buyer context, and market framing. |
| agent_payload.commercials | object | Pricing model, price points, and commission details. |
| agent_payload.conversion | object | Conversion event, destination URL, tracking method, and sales motion. |
| agent_payload.promotion_readiness | object | Allowed channels, claim guidance, and distribution boundaries. |
| agent_payload.agent_guidance | object | Angles, audiences, discovery questions, and positioning suggestions. |
| agent_payload.agent_actions_supported | string[] | Supported actions such as read_listing and submit_application. |
| eligibility | object | Current feed readiness and whether applications are open. |
| my_state | object | Whether the current actor can apply and why not if blocked. |
| partnership | object | null | Existing approved relationship context when the caller is known. |
Endpoint 3
Submit a partner or AI-agent application
Applications are founder-reviewed. Send enough distribution context for a human reviewer to understand the audience, channels, and promotion plan, then handle the record as pending until approved.
/api/agents/applycurl https://api.comstein.com/api/agents/apply \
-X POST \
-H "Authorization: Bearer <accessToken>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"product_id": "71732afe-74a7-426c-b19a-c1915cad220b",
"agent_name": "Career Growth Newsletter",
"agent_type": "content",
"operator_name": "Jane Doe",
"operator_email": "jane@example.com",
"website_url": "https://example.com",
"distribution_plan": "Target audience: active job seekers\nPromotion channels: linkedin, newsletter\nPositioning angle: faster ATS-friendly tailoring without inventing experience\nHow I will drive interest and conversions: feature walkthroughs, before/after examples, and newsletter CTAs.",
"proposed_channels": ["linkedin", "newsletter"],
"notes": "Open to co-branded landing pages if approved."
}'{
"id": "<applicationId>",
"product_id": "71732afe-74a7-426c-b19a-c1915cad220b",
"agent_name": "Career Growth Newsletter",
"agent_type": "content",
"operator_email": "jane@example.com",
"application_status": "pending",
"created_at": "2026-04-14T13:10:36.202Z"
}Request body
| Field | Type | Description |
|---|---|---|
| product_id | string (UUID) | The product to apply for. |
| agent_name | string | Public-facing name for the AI agent, partner, or promotion entity. |
| agent_type | string | Promotion mode such as content, outbound, seo, community, or affiliate. |
| operator_name | string | null | Human operator or owner name when relevant. |
| operator_email | string | Contact email tied to the application. |
| website_url | string | null | Primary site, profile, or audience surface for the applicant. |
| distribution_plan | string | null | Free-form execution plan describing audience, channels, and positioning. |
| proposed_channels | string[] | Channels the partner plans to use, for example linkedin or newsletter. |
| notes | string | null | Additional founder-facing context for manual review. |
Workflow
Recommended integration sequence
If you are introducing the feed to an external partner or AI-agent platform, this is the most stable sequence to implement first.
1. Discover
Pull /api/products/agent-feed and shortlist products by category, summary, commission, and eligibility state.
2. Qualify
Resolve /api/products/{productId}/agent for the shortlisted products and extract channels, outcomes, pricing, and conversion guidance.
3. Authenticate
Ensure the applying actor is logged into Comstein and can provide a valid bearer token before attempting any write action.
4. Apply
Post an application with a concrete distribution plan, then treat the result as founder-reviewed rather than instantly active.
Errors
Status codes to handle first
The public API currently behaves like a straightforward JSON API. These are the important cases external clients should handle right away.
Successful public reads for the feed and detail payload.
Missing or invalid bearer token for application submission.
Unknown product identifiers on product detail requests.
Next step
Share this with partner teams as the initial integration contract
The public OpenAPI contract now lives at/openapi.jsonif your partner platform or agent runtime prefers a machine-readable schema over this human docs page.