Projects API

The Projects API provides a suite of endpoints to manage your projects, briefs, and keywords. All endpoints are available under the /v1/projects path.

Authentication

All requests to the Projects API must be authenticated using a Bearer token in the Authorization header.

Authorization: Bearer <YOUR_API_KEY>

The Project Object

A project object represents a project in your account. It contains not only basic information but also detailed brand intelligence and competitor data.

Attribute	Type	Description
`project_id`	`integer`	The unique identifier for the project.
`created_at`	`string`	The date and time the project was created.
`main_url`	`string`	The main URL associated with the project.
`project_name`	`string`	The name of the project.
`updated_at`	`string`	The date and time the project was last updated.
`status`	`string`	The current status of the project (e.g., `active`).
`brand_intelligence`	`object`	An object containing detailed brand information. See below.
`competitors`	`array`	A list of competitor URLs.

The Brand Intelligence Object

This object provides deep insights into the project's brand, audience, and market positioning.

Attribute	Type	Description
`user_declared_audience`	`string`	The audience as described by the user.
`audience_pain_points`	`array`	A list of pain points experienced by the target audience.
`benefits`	`array`	A list of benefits your product/service offers.
`features`	`array`	A list of key product/service features.
`short_product_description`	`string`	A concise description of the product or service.
`yahini_generated_audience`	`array`	A list of audience segments identified by Yahini.
`user_declared_topics`	`string`	Topics of interest as declared by the user.
`use_cases`	`array`	A list of common use cases for the product/service.

The Brief Object

A brief object contains the generated content brief for a specific keyword.

Attribute	Type	Description
`brief`	`string`	The full content of the generated brief.
`created_at`	`string`	The date and time the brief was created.
`meta_description`	`string`	A suggested meta description for the content.
`meta_title`	`string`	A suggested meta title for the content.
`primary_keyword`	`string`	The primary keyword the brief is based on.
`wordcount`	`string`	The suggested word count range for the content.
`keyword_id`	`integer`	The ID of the keyword associated with this brief.

The Keyword Object

A keyword object represents a single keyword within a project.

Attribute	Type	Description
`archived`	`boolean`	Whether the keyword is archived.
`brief`	`boolean`	Whether a brief has been generated for this keyword.
`competition_level`	`integer`	The competitive level of the keyword.
`created_at`	`string`	The date and time the keyword was added.
`funnel_stage`	`string`	The marketing funnel stage (e.g., `BOFU`).
`is_generating_brief`	`boolean`	Whether a brief is currently being generated.
`keyword_difficulty`	`integer`	The keyword difficulty score.
`keyword_id`	`integer`	The unique identifier for the keyword.
`keyword_tag`	`string`	Any tags associated with the keyword.
`primary_keyword`	`string`	The keyword phrase.
`priority`	`integer`	The priority level of the keyword.
`search_volume`	`integer`	The estimated monthly search volume.
`secondary_keywords`	`array`	A list of related secondary keywords.
`selected`	`boolean`	Whether the keyword is selected.
`updated_at`	`string`	The date and time the keyword was last updated.
`user_generated`	`boolean`	Whether the keyword was added by a user.
`working_title`	`string`	A working title for content based on this keyword.

Project Endpoints

List All Projects

Retrieves a list of all projects associated with your account.

GET /v1/projects

Example Request

curl "https://api.yahini.io/v1/projects" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Get a Single Project

Retrieves a single project by its ID. This provides a detailed view of the project, including its brand intelligence.

GET /v1/projects/:projectId

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project to retrieve.

Example Request

curl "https://api.yahini.io/v1/projects/374" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Brief Endpoints

List All Briefs for a Project

Retrieves a list of all generated briefs for a specific project. You can use query parameters to paginate the results.

GET /v1/projects/:projectId/briefs

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.

Query Parameters

Parameter	Type	Description
`limit`	`integer`	The maximum number of briefs to return. Defaults to all.

Example Request

curl "https://api.yahini.io/v1/projects/374/briefs" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Get a Single Brief

Retrieves a single brief by its associated keyword ID.

GET /v1/projects/:projectId/briefs/:keywordId

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.
`keywordId`	`string`	Required. The ID of the keyword associated with the brief.

Example Request

curl "https://api.yahini.io/v1/projects/374/briefs/36543" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Generate Briefs

Generates briefs for one or more keywords in a project. This is an asynchronous operation. The API will accept the request and start processing in the background.

POST /v1/projects/:projectId/briefs

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.

Body Parameters

Parameter	Type	Description
`keywords`	`array`	Required. An array of keyword IDs to generate briefs for.
`enhance_brief_instructions`	`string`	Optional. If a brief for a specified keyword already exists, you must provide instructions here to regenerate it. This prevents accidental overwrites and ensures that regeneration is intentional. This parameter is only considered when regenerating a single brief.

Example Request

curl -X POST "https://api.yahini.io/v1/projects/374/briefs" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": [36543, 36684]
  }'

Keyword Endpoints

List All Keywords for a Project

Retrieves a list of all keywords for a specific project. You can use query parameters to filter, sort, and paginate the results.

GET /v1/projects/:projectId/keywords

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.

Query Parameters

Parameter	Type	Description
`limit`	`integer`	The maximum number of keywords to return.
`sort_by`	`string`	The field to sort the keywords by (e.g., `search_volume`).
`order`	`string`	The order to sort in (`asc` or `desc`).
`[any]`	`any`	You can filter by any attribute of the keyword object (e.g., `funnel_stage=BOFU`).

Example Request

curl "https://api.yahini.io/v1/projects/374/keywords?limit=10&sort_by=priority&order=desc" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Get a Single Keyword

Retrieves a single keyword by its ID.

GET /v1/projects/:projectId/keywords/:keywordId

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.
`keywordId`	`string`	Required. The ID of the keyword.

Example Request

curl "https://api.yahini.io/v1/projects/374/keywords/15131" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Import Keywords

Imports a list of new keywords into a project. This is an asynchronous operation. The API will accept the request and start processing in the background.

POST /v1/projects/:projectId/keywords

Path Parameters

Parameter	Type	Description
`projectId`	`string`	Required. The ID of the project.

Body Parameters

The body must be an object containing a keywords property, which is an array of keyword objects. You can import up to 200 keywords at a time.

Each keyword object in the keywords array can have the following attributes:

Attribute	Type	Required	Description
`primary_keyword`	`string`	Yes	The main keyword phrase.
`search_volume`	`integer`	Yes	The estimated monthly search volume. Must be a non-negative number.
`secondary_keywords`	`array`	No	An array of related secondary keywords (strings). Up to 10 are allowed.
`keyword_difficulty`	`integer`	No	The keyword difficulty score.
`priority`	`integer`	No	The priority of the keyword, from 1 (lowest) to 4 (highest).
`funnel_stage`	`string`	No	The marketing funnel stage. Must be one of `TOFU`, `MOFU`, or `BOFU`.

Example Request

curl -X POST "https://api.yahini.io/v1/projects/374/keywords" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": [
      {
        "primary_keyword": "Hono",
        "search_volume": 12000,
        "funnel_stage": "BOFU",
        "priority": 4
      },
      {
        "primary_keyword": "Cloudflare Workers",
        "search_volume": 25000,
        "secondary_keywords": ["cloudflare", "serverless"],
        "keyword_difficulty": 65
      }
    ]
  }'

Authentication​

The Project Object​

The Brand Intelligence Object​

The Brief Object​

The Keyword Object​

Project Endpoints​

List All Projects​

Example Request​

Get a Single Project​

Path Parameters​

Example Request​

Brief Endpoints​

List All Briefs for a Project​

Path Parameters​

Query Parameters​

Example Request​

Get a Single Brief​

Path Parameters​

Example Request​

Generate Briefs​

Path Parameters​

Body Parameters​

Example Request​

Keyword Endpoints​

List All Keywords for a Project​

Path Parameters​

Query Parameters​

Example Request​

Get a Single Keyword​

Path Parameters​

Example Request​

Import Keywords​

Path Parameters​

Body Parameters​

Example Request​

Authentication

The Project Object

The Brand Intelligence Object

The Brief Object

The Keyword Object

Project Endpoints

List All Projects

Example Request

Get a Single Project

Path Parameters

Example Request

Brief Endpoints

List All Briefs for a Project

Path Parameters

Query Parameters

Example Request

Get a Single Brief

Path Parameters

Example Request

Generate Briefs

Path Parameters

Body Parameters

Example Request

Keyword Endpoints

List All Keywords for a Project

Path Parameters

Query Parameters

Example Request

Get a Single Keyword

Path Parameters

Example Request

Import Keywords

Path Parameters

Body Parameters

Example Request