Create a Proto

POST /apisix/admin/protos

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

Admin API key configured in config.yaml under deployment.admin.admin_key. You can also pass the key as a query parameter api_key or cookie x_api_key.

In: header

Query Parameters

ttl?integer

Time-to-live in seconds. The resource is automatically removed when it expires.

Range1 <= value

Request Body

application/json

Proto configuration body for create / replace / patch.

Protocol buffer definition for gRPC transcoding.

id?|

Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.

name?string

Human-readable name.

Length1 <= length <= 256

desc?string

Description.

Lengthlength <= 256

labels?

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

content*string

Protobuf .proto file content as a string.

Length1 <= length <= 1048576

Response Body

`application/json`

curl -X POST "http://127.0.0.1:9180/apisix/admin/protos?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "content": "syntax = \\"proto3\\";\\n\\npackage helloworld;\\n\\nservice Greeter {\\n  rpc SayHello (HelloRequest) returns (HelloReply) {}\\n}\\n\\nmessage HelloRequest {\\n  string name = 1;\\n}\\n\\nmessage HelloReply {\\n  string message = 1;\\n}"  }'

Created

{
  "key": "/apisix/protos/00000000000000000293",
  "value": {
    "create_time": 1684752743,
    "update_time": 1684752743,
    "content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
    "id": "00000000000000000293"
  }
}

Invalid configuration

{
  "error_msg": "invalid configuration: property \"uri\" is required"
}

{
  "error_msg": "invalid request body: unexpected character at line 1 column 2"
}

**Unauthorized** — The API key is missing, invalid, or lacks permission.

{
  "error_msg": "failed to check token",
  "description": "missing apikey"
}

{
  "error_msg": "failed to check token",
  "description": "wrong apikey"
}

{
  "error_msg": "failed to check token",
  "description": "invalid method for role viewer"
}

Complete operation details and schema variants

POST /apisix/admin/protos

Create a Proto

Upload a new protobuf definition with an auto-generated ID.

Parameters

ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Proto configuration body for create / replace / patch.

Content type: application/json

id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
name (string, optional): Human-readable name.
desc (string, optional): Description.
labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
create_time (integer, optional): Unix timestamp of creation. Read-only.
update_time (integer, optional): Unix timestamp of last update. Read-only.
content (string, required): Protobuf .proto file content as a string.

Responses

201: Created
key (string, required):
value (object, required): Protocol buffer definition for gRPC transcoding.
value.id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
value.name (string, optional): Human-readable name.
value.desc (string, optional): Description.
value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
value.create_time (integer, optional): Unix timestamp of creation. Read-only.
value.update_time (integer, optional): Unix timestamp of last update. Read-only.
value.content (string, required): Protobuf .proto file content as a string.
createdIndex (integer, optional):
modifiedIndex (integer, optional):
400: Bad Request — The request body is invalid or missing required fields.
error_msg (string, required): Human-readable error message describing what went wrong.
401: Unauthorized — The API key is missing, invalid, or lacks permission.
error_msg (string, required): Authentication error message.
description (string, optional): Detailed reason for the authentication failure.

cURL

curl -X POST 'http://127.0.0.1:9180/apisix/admin/protos'

Create a Proto

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`