--- title: "Create an endpoint" method: POST path: "/v1/projects/{projectID}/endpoints" tags: ["Endpoints"] --- # Create an endpoint `POST /v1/projects/{projectID}/endpoints` This endpoint creates an endpoint ## Path parameters - `projectID` string, required ## Request body - ModelsCreateEndpoint - `advanced_signatures` boolean — Convoy supports two [signature formats](https://getconvoy.io/docs/product-manual/signatures) -- simple or advanced. If left unspecified, we default to false. - `appID` string — Deprecated but necessary for backward compatibility - `authentication` ModelsEndpointAuthentication - `api_key` ModelsApiKey - `header_name` string, required - `header_value` string, required - `basic_auth` ModelsBasicAuth - `password` string, required - `username` string, required - `oauth2` ModelsOAuth2 - `audience` string - `authentication_type` string - `client_id` string - `client_secret` string - `expiry_time_unit` string — Expiry time unit (seconds, milliseconds, minutes, hours) - `field_mapping` ModelsOAuth2FieldMapping - `access_token` string — Field name for access token (e.g., "accessToken", "access_token", "token") - `expires_in` string — Field name for expiry time (e.g., "expiresIn", "expires_in", "expiresAt") - `token_type` string — Field name for token type (e.g., "tokenType", "token_type") - `grant_type` string - `issuer` string - `scope` string - `signing_algorithm` string - `signing_key` ModelsOAuth2SigningKey - `crv` string — EC (Elliptic Curve) key fields - `d` string — Private key (EC) or private exponent (RSA) - `dp` string — RSA first factor CRT exponent (RSA private key only) - `dq` string — RSA second factor CRT exponent (RSA private key only) - `e` string — RSA public exponent (RSA only) - `kid` string — Key ID - `kty` string — Key type: "EC" or "RSA" - `n` string — RSA key fields - `p` string — RSA first prime factor (RSA private key only) - `q` string — RSA second prime factor (RSA private key only) - `qi` string — RSA first CRT coefficient (RSA private key only) - `x` string — X coordinate (EC only) - `y` string — Y coordinate (EC only) - `subject` string - `url` string - `type` 'api_key' | 'oauth2' | 'basic_auth' - `content_type` string — Content type for the endpoint. Defaults to application/json if not specified. - `description` string — Human-readable description of the endpoint. Think of this as metadata describing the endpoint - `http_timeout` integer — Define endpoint http timeout in seconds. - `is_disabled` boolean — This is used to manually enable/disable the endpoint. - `mtls_client_cert` ModelsMtlsClientCert - `client_cert` string — ClientCert is the client certificate PEM string - `client_key` string — ClientKey is the client private key PEM string - `name` string — Endpoint name. - `owner_id` string — The OwnerID is used to group more than one endpoint together to achieve [fanout](https://getconvoy.io/docs/manual/endpoints#Endpoint%20Owner%20ID) - `rate_limit` integer — Rate limit is the total number of requests to be sent to an endpoint in the time duration specified in RateLimitDuration - `rate_limit_duration` integer — Rate limit duration specifies the time range for the rate limit. - `secret` string — Endpoint's webhook secret. If not provided, Convoy autogenerates one for the endpoint. - `slack_webhook_url` string — Slack webhook URL is an alternative method to support email where endpoint developers can receive failure notifications on a slack channel. - `support_email` string — Endpoint developers support email. This is used for communicating endpoint state changes. You should always turn this on when disabling endpoints are enabled. - `url` string — URL is the endpoint's URL prefixed with https. non-https urls are currently not supported. ## Response `201` Created - object - `message` string - `status` boolean - `data` ModelsEndpointResponse - `advanced_signatures` boolean - `authentication` DatastoreEndpointAuthentication - `api_key` DatastoreApiKey - `header_name` string - `header_value` string - `basic_auth` DatastoreBasicAuth - `password` string - `username` string - `oauth2` DatastoreOAuth2 - `audience` string - `authentication_type` 'shared_secret' | 'client_assertion' - `client_id` string - `client_secret` string — Encrypted at rest - `expiry_time_unit` 'seconds' | 'milliseconds' | 'minutes' | 'hours' - `field_mapping` DatastoreOAuth2FieldMapping - `access_token` string — Field name for access token (e.g., "accessToken", "access_token", "token") - `expires_in` string — Field name for expiry time (e.g., "expiresIn", "expires_in", "expiresAt") - `token_type` string — Field name for token type (e.g., "tokenType", "token_type") - `grant_type` string - `issuer` string - `scope` string - `signing_algorithm` string - `signing_key` DatastoreOAuth2SigningKey - `crv` string — EC (Elliptic Curve) key fields - `d` string — Private key (EC only) - `dp` string — RSA first factor CRT exponent (RSA private key only) - `dq` string — RSA second factor CRT exponent (RSA private key only) - `e` string — RSA public exponent (RSA only) - `kid` string — Key ID - `kty` string — Key type: "EC" or "RSA" - `n` string — RSA key fields - `p` string — RSA first prime factor (RSA private key only) - `q` string — RSA second prime factor (RSA private key only) - `qi` string — RSA first CRT coefficient (RSA private key only) - `x` string — X coordinate (EC only) - `y` string — Y coordinate (EC only) - `subject` string - `url` string - `type` 'api_key' | 'oauth2' | 'basic_auth' - `content_type` string - `created_at` string - `deleted_at` string - `description` string - `events` integer - `failure_rate` number - `http_timeout` integer - `mtls_client_cert` DatastoreMtlsClientCert - `client_cert` string — ClientCert is the client certificate PEM string - `client_key` string — ClientKey is the client private key PEM string - `name` string - `owner_id` string - `project_id` string - `rate_limit` integer - `rate_limit_duration` integer - `secrets` DatastoreSecret[] - `created_at` string - `deleted_at` string - `expires_at` string - `uid` string - `updated_at` string - `value` string - `slack_webhook_url` string - `status` 'active' | 'inactive' | 'paused' - `support_email` string - `uid` string - `updated_at` string - `url` string ## Other responses - `400` — Bad Request - `401` — Unauthorized - `404` — Not Found ## Changes - **2026-03-19** (v3) `990a51cff1cc` — 1 warning, 3 info - added the new `basic_auth` enum value to the `allOf[subschema #2]/data/authentication/type` response property for the response status `201` - added the new optional request property `authentication/allOf[#/components/schemas/models.EndpointAuthentication]/basic_auth` - added the new `basic_auth` enum value to the request property `authentication/allOf[#/components/schemas/models.EndpointAuthentication]/type` - added the optional property `allOf[subschema #2]/data/authentication/basic_auth` to the response with the `201` status - **2025-12-04** (v3) `af9526d13dc8` — 1 info - removed the `pending` enum value from the `allOf[subschema #2]/data/status` response property for the response status `201` - **2025-11-27** (v3) `88eaa000293b` — 1 warning, 3 info - added the new `oauth2` enum value to the `allOf[subschema #2]/data/authentication/type` response property for the response status `201` - added the new optional request property `authentication/allOf[#/components/schemas/models.EndpointAuthentication]/oauth2` - added the new `oauth2` enum value to the request property `authentication/allOf[#/components/schemas/models.EndpointAuthentication]/type` - added the optional property `allOf[subschema #2]/data/authentication/oauth2` to the response with the `201` status - …earlier changes not shown [Full history](https://skmtc.dev/getconvoy/apis/convoy-api-reference/changes/v1/projects/:projectID/endpoints/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/274ed78eabfc/schema)