> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Prompts > Creates one or more prompts on a project. **Side effects — this is not a passive write:** - Adding new active prompts normally **starts a data collection run**, which **consumes credits**. Exception: projects on a manual schedule do not auto-run after their first run — for those you must request a run separately. - A **keyword** and **search volume** are generated automatically for each new prompt by the pipeline; you cannot supply them. Duplicates of existing prompts (same text + country) are not re-created: an inactive duplicate is reactivated, and tag/topic changes are merged onto the existing prompt. New prompts are created with status `active`. Requests are rejected when they would exceed the project's prompt limit or the team's available credits. ## OpenAPI ````yaml /openapi.json post /api/v1/projects/{project}/prompts openapi: 3.1.0 info: title: Surfacd Public API version: 1.0.0 description: >- Public API for Surfacd. Team-scoped operations live under `/api/v1/team/...`; project collections live under `/api/v1/projects`; project-scoped operations live under `/api/v1/projects/{project}/...`. All endpoints require a Bearer team API key created in Team Settings. The API key selects the team for team-level and collection endpoints. servers: - url: https://app.surfacd.com description: Production security: - bearerAuth: [] tags: - name: Projects description: Project management endpoints. Reads only in this version. - name: Prompts description: Prompt management endpoints. Reads only in this version. - name: Team description: Team settings and plan details for the current team. - name: Reporting description: >- Read-only reporting endpoints for projects (brand rankings, mentions, visibility, matrix analysis, source data). - name: Reference description: Reference data used by create, update, and reporting filters. - name: Tags description: Project tag management endpoints. paths: /api/v1/projects/{project}/prompts: parameters: - $ref: '#/components/parameters/ProjectUuid' post: tags: - Prompts summary: Create Prompts description: >- Creates one or more prompts on a project. **Side effects — this is not a passive write:** - Adding new active prompts normally **starts a data collection run**, which **consumes credits**. Exception: projects on a manual schedule do not auto-run after their first run — for those you must request a run separately. - A **keyword** and **search volume** are generated automatically for each new prompt by the pipeline; you cannot supply them. Duplicates of existing prompts (same text + country) are not re-created: an inactive duplicate is reactivated, and tag/topic changes are merged onto the existing prompt. New prompts are created with status `active`. Requests are rejected when they would exceed the project's prompt limit or the team's available credits. operationId: v1ProjectsPromptsStore requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePromptsRequest' responses: '201': description: Result summary with the newly created prompts. content: application/json: schema: $ref: '#/components/schemas/CreatePromptsResult' '404': description: Project not found in the current team. content: application/json: schema: type: object properties: message: type: string required: - message '422': $ref: '#/components/responses/ValidationError' components: parameters: ProjectUuid: name: project in: path required: true description: Project UUID. schema: type: string format: uuid schemas: CreatePromptsRequest: type: object properties: prompts: type: array minItems: 1 maxItems: 200 items: $ref: '#/components/schemas/CreatePromptInput' required: - prompts CreatePromptsResult: type: object properties: created: type: integer description: Number of new prompts created. skipped: type: integer description: Number of duplicates skipped with no change. updated: type: integer description: Number of existing prompts whose tags/topic were merged. activated: type: integer description: Number of existing inactive prompts reactivated. prompts: type: array items: $ref: '#/components/schemas/Prompt' description: >- The newly created prompts (excludes skipped, updated, and reactivated). required: - created - skipped - updated - activated - prompts CreatePromptInput: type: object properties: text: type: string maxLength: 700 description: The prompt text. country_code: type: - string - 'null' description: >- ISO 3166-1 alpha-2 country code. Falls back to the project's default country when omitted. topic: type: - string - 'null' maxLength: 255 description: Topic name. Created on the project if it does not already exist. tags: type: array items: type: string format: uuid description: >- Existing tag UUIDs to attach. Create or list tags with `/api/v1/projects/{project}/tags`; tag names are not accepted here. required: - text Prompt: type: object properties: uuid: type: string format: uuid text: type: string description: The prompt text. keyword: type: - string - 'null' status: $ref: '#/components/schemas/PromptStatus' search_volume: type: - integer - 'null' description: Most recent search volume for the prompt's keyword, when known. topic: oneOf: - $ref: '#/components/schemas/PromptTopic' - type: 'null' country: $ref: '#/components/schemas/ProjectCountry' tags: type: array items: $ref: '#/components/schemas/PromptTag' created_at: type: string format: date-time updated_at: type: string format: date-time required: - uuid - text - keyword - status - search_volume - topic - country - tags - created_at - updated_at ValidationError: type: object description: Returned when one or more request parameters fail validation. properties: message: type: string errors: type: object additionalProperties: type: array items: type: string required: - message - errors PromptStatus: type: string enum: - suggestion - declined - inactive - active PromptTopic: type: object properties: uuid: type: string format: uuid name: type: string required: - uuid - name ProjectCountry: type: object properties: code: type: string description: ISO 3166-1 alpha-2 country code (lowercase). name: type: string required: - code - name PromptTag: type: object properties: uuid: type: string format: uuid name: type: string color: type: - string - 'null' required: - uuid - name - color responses: ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: token description: >- Team API key created in Team Settings. Use it with URLs for the same team. ````