Skip to content
MicroVisualizer

Create a new service in the project

POST
/v1/projects/{projectId}/services

Adds a microservice definition to the project with properties like name, category, owner, and messaging relationships. Services can produce to and consume from messaging topics to document data flows. Service names must be unique within the project and will be automatically converted to URL-friendly slugs.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
projectId
required

An identifier (e.g., my-project-a1b2c)

string
>= 8 characters <= 60 characters /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

Request Body required

Section titled “Request Body required ”

The service

object
name
required

The name of this service

string
>= 1 characters <= 60 characters
description

A description of this service

string
nullable <= 200 characters
category

The category relevant for this service (e.g. billing, reporting, etc.)

string
nullable >= 1 characters <= 60 characters
owner

The name of the team that owns this service

string
nullable >= 1 characters <= 60 characters
flows

The flows that this service belongs to

Array<string>
nullable
consumes
Array<object>

A messaging topic (Kafka, RabbitMQ, etc.) that services can produce to or consume from

object
name
required

The name of the messaging topic (e.g., “order.created”, “payment-queue”)

string
>= 1 characters <= 255 characters
category

The category relevant for this topic (e.g. billing, reporting, etc.)

string
nullable >= 1 characters <= 60 characters
owner

The name of the team that owns this topic

string
nullable >= 1 characters <= 60 characters
flows

The flows that this topic belongs to

Array<string>
nullable
extras

Custom key-value fields (max 20 pairs, keys max 100 chars, values max 500 chars)

object
<= 20 properties
key
additional properties
string
<= 500 characters
produces
Array<object>

A messaging topic (Kafka, RabbitMQ, etc.) that services can produce to or consume from

object
name
required

The name of the messaging topic (e.g., “order.created”, “payment-queue”)

string
>= 1 characters <= 255 characters
category

The category relevant for this topic (e.g. billing, reporting, etc.)

string
nullable >= 1 characters <= 60 characters
owner

The name of the team that owns this topic

string
nullable >= 1 characters <= 60 characters
flows

The flows that this topic belongs to

Array<string>
nullable
extras

Custom key-value fields (max 20 pairs, keys max 100 chars, values max 500 chars)

object
<= 20 properties
key
additional properties
string
<= 500 characters
extras

Custom key-value fields (max 20 pairs, keys max 100 chars, values max 500 chars)

object
<= 20 properties
key
additional properties
string
<= 500 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The created service

The service

object
slug
required

The URL-friendly slug of the service

string
name
required

The name of this service

string
>= 1 characters <= 60 characters
description

A description of this service

string
<= 200 characters
category

The category relevant for this service (e.g. billing, reporting, etc.)

string
>= 1 characters <= 60 characters
owner

The name of the team that owns this service

string
>= 1 characters <= 60 characters
flows

The flows that this service belongs to

Array<string>
consumes
Array<object>

A messaging topic (Kafka, RabbitMQ, etc.) that services can produce to or consume from

object
name
required

The name of the messaging topic (e.g., “order.created”, “payment-queue”)

string
>= 1 characters <= 255 characters
category

The category relevant for this topic (e.g. billing, reporting, etc.)

string
nullable >= 1 characters <= 60 characters
owner

The name of the team that owns this topic

string
nullable >= 1 characters <= 60 characters
flows

The flows that this topic belongs to

Array<string>
nullable
extras

Custom key-value fields (max 20 pairs, keys max 100 chars, values max 500 chars)

object
<= 20 properties
key
additional properties
string
<= 500 characters
produces
Array<object>

A messaging topic (Kafka, RabbitMQ, etc.) that services can produce to or consume from

object
name
required

The name of the messaging topic (e.g., “order.created”, “payment-queue”)

string
>= 1 characters <= 255 characters
category

The category relevant for this topic (e.g. billing, reporting, etc.)

string
nullable >= 1 characters <= 60 characters
owner

The name of the team that owns this topic

string
nullable >= 1 characters <= 60 characters
flows

The flows that this topic belongs to

Array<string>
nullable
extras

Custom key-value fields (max 20 pairs, keys max 100 chars, values max 500 chars)

object
<= 20 properties
key
additional properties
string
<= 500 characters
extras

Custom key-value fields

object
key
additional properties
string
createdBy
required

The name of the actor (member email or API key name) that added this service in the project

string
createdByType
required

The type of actor (user or API key)

string
Allowed values: MEMBER API_KEY
createdAt
required

The timestamp in UTC that the service was added to the project

string format: date-time
updatedBy
required

The name of the actor (member email or API key name) that updated this service

string
updatedByType
required

The type of actor (user or API key)

string
Allowed values: MEMBER API_KEY
updatedAt
required

The timestamp in UTC that the service was updated

string format: date-time
validFrom
required

The timestamp in UTC that the service snapshot is valid from

string format: date-time
validUntil

The timestamp in UTC that the service snapshot is valid until (null for the latest service snapshot)

string format: date-time

400

Section titled “400 ”

Validation error

Validation error response with field-level details

object
status
required

HTTP status code

integer
Example
400
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Validation failed
violations
required

List of field validation violations

Array<object>

Individual field validation violation

object
field
required

The field that failed validation

string
Example
name
message
required

Validation error message for this field

string
Example
must not be blank
rejectedValue

The value that was rejected (optional)

nullable

401

Section titled “401 ”

Unauthorized, authentication required

Standard error response

object
status
required

HTTP status code

integer
Example
400
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Validation failed
details

Additional error details

string
Example
Project name must be between 3 and 60 characters

404

Section titled “404 ”

Project not found

Standard error response

object
status
required

HTTP status code

integer
Example
400
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Validation failed
details

Additional error details

string
Example
Project name must be between 3 and 60 characters

409

Section titled “409 ”

Service with this name already exists in the project

Standard error response

object
status
required

HTTP status code

integer
Example
400
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Validation failed
details

Additional error details

string
Example
Project name must be between 3 and 60 characters

429

Section titled “429 ”

Too many requests

Rate limit exceeded error response

object
status
required

HTTP status code

integer
Example
429
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Too many requests
retryAfter
required

Number of seconds until the client can retry

integer
Example
60

Headers

Section titled “Headers ”
Retry-After
integer

Number of seconds to wait before retrying

500

Section titled “500 ”

Internal server error

Standard error response

object
status
required

HTTP status code

integer
Example
400
code
required

Machine-readable error code in snake_case

string
Allowed values: bad_request unauthorized payment_required forbidden not_found conflict rate_limited internal_error project_not_found project_limit_reached service_not_found service_name_conflict subscription_not_found customer_not_found insufficient_ai_credits invalid_billing_cycle validation_failed resource_already_exists public_share_token_not_found
message
required

Error message

string
Example
Validation failed
details

Additional error details

string
Example
Project name must be between 3 and 60 characters