Positioning

REST endpoints for Positioning. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

Get latest positioning data

GET/v1/projects/{projectId}/positioning

Get the latest positioning data for all competitors in a project. Returns homepage messaging, value propositions, CTAs, target audience, and competitive messaging analysis.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/positioning" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "lastUpdatedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "competitorsChecked": 6,
      "competitorsSuccessful": 5,
      "customer": {
        "domain": "yoursite.com",
        "messagingStrengthScore": 72,
        "hasSpecificHeadline": true,
        "hasStrongCta": true,
        "showsPricing": false,
        "hasFreeTrial": true,
        "primaryCta": "Start Free Trial",
        "mainHeadline": "Ship Projects 10x Faster"
      },
      "topMessagingCompetitor": {
        "domain": "rival.com",
        "messagingStrengthScore": 88,
        "primaryCta": "Try It Free",
        "mainHeadline": "The Future of Work"
      },
      "ctaComparison": {
        "yourCta": "Start Free Trial",
        "strongestCompetitorCta": "Get Started — It's Free",
        "strongestCompetitorDomain": "rival.com"
      },
      "pricingComparison": {
        "competitorsShowingPrice": 3,
        "competitorsWithFreeTrial": 4,
        "youShowPrice": false,
        "youHaveFreeTrial": true
      },
      "messagingScoreGap": -16
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "homepageUrl": "https://competitor.com",
        "content": {
          "pageTitle": "Acme - The #1 Project Management Tool",
          "pageDescription": "Manage projects, track tasks, and collaborate with your team.",
          "mainHeadline": "Ship Projects 10x Faster",
          "tagline": "The all-in-one platform for modern teams",
          "valueProposition": "Streamline your workflow with AI-powered project management",
          "primaryCTA": "Start Free Trial",
          "secondaryCTA": "Book a Demo",
          "keyOfferings": [
            "Task Management",
            "Time Tracking",
            "Team Collaboration"
          ],
          "targetAudience": "Product teams and agencies",
          "mainDifferentiator": "AI-powered automation that saves 5 hours per week",
          "pricingMentioned": true,
          "startingPrice": "$9/month",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days"
        }
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`lastUpdatedAt`	`string`	When this data was last updated (ISO-8601)
`summary`	`object`	Run summary with messaging gap analysis. See `item.summary`.
`competitors`	`array<object>`	Per-competitor positioning data. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `item.summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `item.summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `item.summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `item.summary.pricingComparison`.
`messagingScoreGap`	`number`	Your messaging score minus top competitor score (negative = you are behind)

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`homepageUrl`	`string`	Homepage URL that was analyzed
`content`	`object`	Extracted homepage content and messaging. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number`	Messaging strength score (0-100) based on homepage completeness
`hasSpecificHeadline`	`boolean`	Whether your headline includes specific metrics or numbers
`hasStrongCta`	`boolean`	Whether your CTA is strong and specific (not just ‘Get Started’)
`showsPricing`	`boolean`	Whether pricing is shown on your homepage
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`primaryCta`	`string`	Your primary CTA text
`mainHeadline`	`string`	Your main headline

item.summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

item.summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string`	Your primary CTA text
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

item.summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean`	Whether you show pricing on your homepage
`youHaveFreeTrial`	`boolean`	Whether you offer a free trial

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main homepage headline
`tagline`	`string`	Tagline or subheadline
`valueProposition`	`string`	Core value proposition statement
`primaryCTA`	`string`	Primary call-to-action text
`secondaryCTA`	`string`	Secondary call-to-action text
`keyOfferings`	`array<string>`	Key product offerings listed on homepage
`targetAudience`	`string`	Target audience as described on homepage
`mainDifferentiator`	`string`	Main differentiator or unique selling point
`pricingMentioned`	`boolean`	Whether pricing is mentioned on the homepage
`startingPrice`	`string`	Starting price if mentioned on homepage
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`project_not_found`	No `project` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get positioning run history

GET/v1/projects/{projectId}/positioning/history

Get paginated history of positioning monitoring runs for a project. Each entry includes run timing and summary statistics with messaging gap analysis.

Returns · { items, pagination }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Required	Description
`page`	`number`		Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`		Number of items per page. Default `20`. Range `1`–`100`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/positioning/history?page=1&limit=20" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "runId": "507f1f77bcf86cd799439011",
      "completedAt": "2026-03-15T10:00:00.000Z",
      "summary": {
        "competitorsChecked": 6,
        "competitorsSuccessful": 5,
        "customer": {
          "domain": "yoursite.com",
          "messagingStrengthScore": 72,
          "hasSpecificHeadline": true,
          "hasStrongCta": true,
          "showsPricing": false,
          "hasFreeTrial": true,
          "primaryCta": "Start Free Trial",
          "mainHeadline": "Ship Projects 10x Faster"
        },
        "topMessagingCompetitor": {
          "domain": "rival.com",
          "messagingStrengthScore": 88,
          "primaryCta": "Try It Free",
          "mainHeadline": "The Future of Work"
        },
        "ctaComparison": {
          "yourCta": "Start Free Trial",
          "strongestCompetitorCta": "Get Started — It's Free",
          "strongestCompetitorDomain": "rival.com"
        },
        "pricingComparison": {
          "competitorsShowingPrice": 3,
          "competitorsWithFreeTrial": 4,
          "youShowPrice": false,
          "youHaveFreeTrial": true
        },
        "messagingScoreGap": -16
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Fields

items[] — each entry

Field	Type	Description
`runId`	`string`	Run ID
`completedAt`	`string`	When this run completed (ISO-8601)
`summary`	`object`	Run summary statistics. See `items[].summary`.

pagination — object

Field	Type	Description
`page`	`number`	Current page number (1-indexed)
`limit`	`number`	Number of items per page
`total`	`number`	Total number of items across all pages
`totalPages`	`number`	Total number of pages
`hasMore`	`boolean`	Whether more pages exist after the current page

items[].summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `items[].summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `items[].summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `items[].summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `items[].summary.pricingComparison`.
`messagingScoreGap`	`number`	Your messaging score minus top competitor score (negative = you are behind)

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number`	Messaging strength score (0-100) based on homepage completeness
`hasSpecificHeadline`	`boolean`	Whether your headline includes specific metrics or numbers
`hasStrongCta`	`boolean`	Whether your CTA is strong and specific (not just ‘Get Started’)
`showsPricing`	`boolean`	Whether pricing is shown on your homepage
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`primaryCta`	`string`	Your primary CTA text
`mainHeadline`	`string`	Your main headline

items[].summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

items[].summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string`	Your primary CTA text
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

items[].summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean`	Whether you show pricing on your homepage
`youHaveFreeTrial`	`boolean`	Whether you offer a free trial

Paginated — pass page and limit query parameters and follow pagination.hasMore to page through the full set.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get positioning data for a specific run

GET/v1/projects/{projectId}/positioning/history/{runId}

Get full positioning data for a specific historical monitoring run, including per-competitor homepage messaging, value propositions, CTAs, and audience data.

Returns · { item }

Path parameters

Name	Type	Description
`runId`	`string`	Run ID
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/positioning/history/507f1f77bcf86cd799439012" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "runId": "507f1f77bcf86cd799439011",
    "completedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "competitorsChecked": 6,
      "competitorsSuccessful": 5,
      "customer": {
        "domain": "yoursite.com",
        "messagingStrengthScore": 72,
        "hasSpecificHeadline": true,
        "hasStrongCta": true,
        "showsPricing": false,
        "hasFreeTrial": true,
        "primaryCta": "Start Free Trial",
        "mainHeadline": "Ship Projects 10x Faster"
      },
      "topMessagingCompetitor": {
        "domain": "rival.com",
        "messagingStrengthScore": 88,
        "primaryCta": "Try It Free",
        "mainHeadline": "The Future of Work"
      },
      "ctaComparison": {
        "yourCta": "Start Free Trial",
        "strongestCompetitorCta": "Get Started — It's Free",
        "strongestCompetitorDomain": "rival.com"
      },
      "pricingComparison": {
        "competitorsShowingPrice": 3,
        "competitorsWithFreeTrial": 4,
        "youShowPrice": false,
        "youHaveFreeTrial": true
      },
      "messagingScoreGap": -16
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "isOwn": false,
        "homepageUrl": "https://competitor.com",
        "content": {
          "pageTitle": "Acme - The #1 Project Management Tool",
          "pageDescription": "Manage projects, track tasks, and collaborate with your team.",
          "mainHeadline": "Ship Projects 10x Faster",
          "tagline": "The all-in-one platform for modern teams",
          "valueProposition": "Streamline your workflow with AI-powered project management",
          "primaryCTA": "Start Free Trial",
          "secondaryCTA": "Book a Demo",
          "keyOfferings": [
            "Task Management",
            "Time Tracking",
            "Team Collaboration"
          ],
          "targetAudience": "Product teams and agencies",
          "mainDifferentiator": "AI-powered automation that saves 5 hours per week",
          "pricingMentioned": true,
          "startingPrice": "$9/month",
          "hasFreeTrial": true,
          "freeTrialDuration": "14 days"
        }
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`runId`	`string`	Run ID
`completedAt`	`string`	When this run completed (ISO-8601)
`summary`	`object`	Run summary statistics. See `item.summary`.
`competitors`	`array<object>`	Per-competitor positioning data for this run. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`competitorsChecked`	`number`	Number of competitor homepages checked in this run
`competitorsSuccessful`	`number`	Number of competitor homepages successfully analyzed
`customer`	`object`	Your domain’s messaging metrics. See `item.summary.customer`.
`topMessagingCompetitor`	`object \| null`	Competitor with the highest messaging strength score, or null if no competitors checked. Nullable. See `item.summary.topMessagingCompetitor`.
`ctaComparison`	`object \| null`	CTA comparison between you and the strongest competitor, or null if unavailable. Nullable. See `item.summary.ctaComparison`.
`pricingComparison`	`object`	Pricing transparency comparison across competitors. See `item.summary.pricingComparison`.
`messagingScoreGap`	`number`	Your messaging score minus top competitor score (negative = you are behind)

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`isOwn`	`boolean`	Whether this is the project’s own domain
`homepageUrl`	`string`	Homepage URL that was analyzed
`content`	`object`	Extracted homepage content and messaging. See `item.competitors[].content`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Your domain
`messagingStrengthScore`	`number`	Messaging strength score (0-100) based on homepage completeness
`hasSpecificHeadline`	`boolean`	Whether your headline includes specific metrics or numbers
`hasStrongCta`	`boolean`	Whether your CTA is strong and specific (not just ‘Get Started’)
`showsPricing`	`boolean`	Whether pricing is shown on your homepage
`hasFreeTrial`	`boolean`	Whether you offer a free trial
`primaryCta`	`string`	Your primary CTA text
`mainHeadline`	`string`	Your main headline

item.summary.topMessagingCompetitor — object

Field	Type	Description
`domain`	`string`	Top messaging competitor domain
`messagingStrengthScore`	`number`	Their messaging strength score (0-100)
`primaryCta`	`string`	Their primary CTA text
`mainHeadline`	`string`	Their main headline

item.summary.ctaComparison — object

Field	Type	Description
`yourCta`	`string`	Your primary CTA text
`strongestCompetitorCta`	`string`	Strongest competitor’s CTA text
`strongestCompetitorDomain`	`string`	Domain of the competitor with the strongest CTA

item.summary.pricingComparison — object

Field	Type	Description
`competitorsShowingPrice`	`number`	Number of competitors showing pricing on homepage
`competitorsWithFreeTrial`	`number`	Number of competitors offering a free trial
`youShowPrice`	`boolean`	Whether you show pricing on your homepage
`youHaveFreeTrial`	`boolean`	Whether you offer a free trial

item.competitors[].content — object

Field	Type	Description
`pageTitle`	`string`	Page title
`pageDescription`	`string`	Page meta description
`mainHeadline`	`string`	Main homepage headline
`tagline`	`string`	Tagline or subheadline
`valueProposition`	`string`	Core value proposition statement
`primaryCTA`	`string`	Primary call-to-action text
`secondaryCTA`	`string`	Secondary call-to-action text
`keyOfferings`	`array<string>`	Key product offerings listed on homepage
`targetAudience`	`string`	Target audience as described on homepage
`mainDifferentiator`	`string`	Main differentiator or unique selling point
`pricingMentioned`	`boolean`	Whether pricing is mentioned on the homepage
`startingPrice`	`string`	Starting price if mentioned on homepage
`hasFreeTrial`	`boolean`	Whether a free trial is offered
`freeTrialDuration`	`string`	Free trial duration if offered

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`run_not_found`	No `run` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}