---
title: "Create a project"
method: POST
path: "/v1/projects"
tags: ["Projects"]
---

# Create a project

`POST /v1/projects`

This endpoint creates a project. Authenticate with a personal API key or JWT and pass the organisation id as the orgID query parameter. The response includes the project and a one-time project API key.

## Query parameters

- `orgID` string, required

## Request body

- ModelsCreateProject
  - `config` ModelsProjectConfig
    - `add_event_id_trace_headers` boolean — Controls of the Event ID and Event Delivery ID Headers are added to the request when events are dispatched to endpoints
    - `circuit_breaker` DatastoreCircuitBreakerConfiguration
      - `consecutive_failure_threshold` integer
      - `error_timeout` integer
      - `failure_threshold` integer
      - `minimum_request_count` integer
      - `observability_window` integer
      - `sample_rate` integer
      - `success_threshold` integer
    - `disable_endpoint` boolean — Controls if the project will disable and endpoint after the retry threshold for an event is reached
    - `max_payload_read_size` integer — Specifies how many bytes and incoming project should read from the ingest request, and how many bytes an outgoing project should from the response of your endpoints Defaults to 50KB.
    - `meta_event` ModelsMetaEventConfiguration
      - `event_type` string[]
      - `is_enabled` boolean
      - `secret` string
      - `type` string
      - `url` string
    - `multiple_endpoint_subscriptions` boolean — MultipleEndpointSubscriptions is used to configure if multiple subscriptions can be created for the endpoint in a project
    - `ratelimit` ModelsRateLimitConfiguration
      - `count` integer
      - `duration` integer
    - `replay_attacks_prevention_enabled` boolean — Controls if your project will add a timestamp to it's webhook signature header to prevent a replay attack, See this blog post[https://getconvoy.io/blog/generating-stripe-like-webhook-signatures] for more]
    - `request_id_header` 'X-Convoy-Idempotency-Key'
    - `search_policy` string — Specify the interval in hours for which the event tokenizer runs
    - `signature` ModelsSignatureConfiguration
      - `header` 'X-Convoy-Signature'
      - `versions` ModelsSignatureVersion[]
        - `created_at` string
        - `encoding` string
        - `hash` string
        - `uid` string
    - `ssl` ModelsSSLConfiguration
      - `enforce_secure_endpoints` boolean
    - `strategy` ModelsStrategyConfiguration
      - `duration` integer
      - `retry_count` integer
      - `type` string
  - `logo_url` string
  - `name` string — Project Name
  - `type` string — Project Type, supported values are `outgoing`, `incoming`

## Response `201`

Created

- object
  - `message` string
  - `status` boolean
  - `data` ModelsCreateProjectResponse
    - `api_key` DatastoreAPIKeyResponse
      - `created_at` string
      - `expires_at` string
      - `key` string
      - `key_type` string
      - `name` string
      - `role` DatastoreRole
        - `app` string
        - `project` string
        - `type` 'instance_admin' | 'organisation_admin' | 'billing_admin' | 'project_admin' | 'project_viewer' | 'api'
      - `uid` string
      - `user_id` string
    - `project` ModelsProjectResponse
      - `config` DatastoreProjectConfig
        - `add_event_id_trace_headers` boolean
        - `circuit_breaker` DatastoreCircuitBreakerConfiguration
          - `consecutive_failure_threshold` integer
          - `error_timeout` integer
          - `failure_threshold` integer
          - `minimum_request_count` integer
          - `observability_window` integer
          - `sample_rate` integer
          - `success_threshold` integer
        - `disable_endpoint` boolean
        - `max_payload_read_size` integer
        - `meta_event` DatastoreMetaEventConfiguration
          - `event_type` string[]
          - `is_enabled` boolean
          - `pub_sub` DatastorePubSubConfig
            - `amqp` DatastoreAmqpPubSubConfig
              - …
            - `google` DatastoreGooglePubSubConfig
              - …
            - `kafka` DatastoreKafkaPubSubConfig
              - …
            - `sqs` DatastoreSQSPubSubConfig
              - …
            - `type` 'sqs' | 'google' | 'kafka' | 'amqp'
            - `workers` integer
          - `secret` string
          - `type` 'http' | 'pub_sub'
          - `url` string
        - `multiple_endpoint_subscriptions` boolean
        - `ratelimit` DatastoreRateLimitConfiguration
          - `count` integer
          - `duration` integer
        - `replay_attacks_prevention_enabled` boolean
        - `request_id_header` 'X-Convoy-Idempotency-Key'
        - `search_policy` string
        - `signature` DatastoreSignatureConfiguration
          - `header` 'X-Convoy-Signature'
          - `versions` DatastoreSignatureVersion[]
            - `created_at` string
            - `encoding` 'base64' | 'hex'
            - `hash` string
            - `uid` string
        - `ssl` DatastoreSSLConfiguration
          - `enforce_secure_endpoints` boolean
        - `strategy` DatastoreStrategyConfiguration
          - `duration` integer
          - `retry_count` integer
          - `type` 'linear' | 'exponential'
      - `created_at` string
      - `deleted_at` string
      - `logo_url` string
      - `name` string
      - `organisation_id` string
      - `retained_events` integer
      - `statistics` DatastoreProjectStatistics
        - `endpoints_exist` boolean
        - `events_exist` boolean
        - `sources_exist` boolean
        - `subscriptions_exist` boolean
      - `type` 'outgoing' | 'incoming'
      - `uid` string
      - `updated_at` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found

## Changes

- **2026-07-19** (v3) `e171f744d209` — 1 breaking
  - the `allOf[subschema #2]/data/project/allOf[#/components/schemas/models.ProjectResponse]/config/meta_event/pub_sub/google/service_account` response's property type/format changed from `array`/`` to `string`/`byte` for status `201`
- **2026-07-16** (v3) `2206e58b9040` — 2 info
  - added the new optional request property `config/allOf[#/components/schemas/models.ProjectConfig]/request_id_header`
  - added the optional property `allOf[subschema #2]/data/project/allOf[#/components/schemas/models.ProjectResponse]/config/request_id_header` to the response with the `201` status
- **2026-07-14** (v3) `5e18a0a13385` — 1 info
  - endpoint added
- **2024-01-03** (v3) `bbe11224b60e` — 1 breaking
  - api path removed without deprecation
- **2023-11-17** (v3) `41d4fca4cab8` — 1 warning, 5 info
  - added the new `kafka` enum value to the `allOf[subschema #2]/data/project/config/meta_event/pub_sub/type` response property for the response status `200`
  - added the new optional request property `config/add_event_id_trace_headers`
  - added the new optional request property `config/retention_policy/search_policy`
  - added the optional property `allOf[subschema #2]/data/project/config/add_event_id_trace_headers` to the response with the `200` status
  - …2 more

[Change history](https://skmtc.dev/getconvoy/apis/convoy-api-reference/changes/v1/projects/post.md)

---

[API](https://skmtc.dev/getconvoy/apis/convoy-api-reference.md) · [All operations](https://skmtc.dev/getconvoy/apis/convoy-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getconvoy/convoy-api-reference/revisions/e171f744d209/schema)