package user

import "context"

type GetUserParams struct {
    ID string
}

type User struct {
    ID    string `json:"id"`
    Email string `json:"email"`
    Name  string `json:"name"`
}

//encore:api public method=GET path=/users/:id
func GetUser(ctx context.Context, params *GetUserParams) (*User, error) {
    // Implementation
    return &User{ID: params.ID, Email: "user@example.com", Name: "John"}, nil
}

2. POST with Request Body

type CreateUserParams struct {
    Email string `json:"email"`
    Name  string `json:"name"`
}

//encore:api public method=POST path=/users
func CreateUser(ctx context.Context, params *CreateUserParams) (*User, error) {
    // Implementation
    return &User{ID: "new-id", Email: params.Email, Name: params.Name}, nil
}

API Annotation Options

Option	Values	Description
`public`	-	Accessible from outside
`private`	-	Only callable from other services
`auth`	-	Requires authentication
`method`	GET, POST, PUT, PATCH, DELETE	HTTP method
`path`	string	URL path with `:param` for path params
`sensitive`	-	Redacts request/response payloads from traces

Examples

//encore:api public method=GET path=/health
//encore:api private method=POST path=/internal/process
//encore:api auth method=GET path=/profile
//encore:api public sensitive method=POST path=/auth/login

Sensitive Data

Mark sensitive fields to redact them from tracing logs:

type LoginParams struct {
    Email    string `json:"email"`
    Password string `json:"password" encore:"sensitive"`
}

Or mark the entire endpoint as sensitive in the annotation:

//encore:api public sensitive method=POST path=/auth/login
func Login(ctx context.Context, params *LoginParams) (*TokenResponse, error) {
    // Request and response will be redacted from traces
}

Custom HTTP Status Codes

Return custom HTTP status codes using the encore:"httpstatus" tag:

type CreateResponse struct {
    ID     string `json:"id"`
    Status int    `encore:"httpstatus"`
}

//encore:api public method=POST path=/items
func CreateItem(ctx context.Context, params *CreateParams) (*CreateResponse, error) {
    item := createItem(params)
    return &CreateResponse{
        ID:     item.ID,
        Status: 201,  // Returns HTTP 201 Created
    }, nil
}

Request Parameter Sources

Path Parameters

// Path: /users/:id
type GetUserParams struct {
    ID string  // Automatically mapped from :id
}

Query Parameters

// Path: /users
type ListUsersParams struct {
    Limit  int `query:"limit"`
    Offset int `query:"offset"`
}

//encore:api public method=GET path=/users
func ListUsers(ctx context.Context, params *ListUsersParams) (*ListResponse, error) {
    // params.Limit and params.Offset come from query string
}

Headers

type WebhookParams struct {
    Signature string `header:"X-Webhook-Signature"`
    Payload   string `json:"payload"`
}

Cookies

import "net/http"

type AuthParams struct {
    SessionCookie *http.Cookie `cookie:"session"`
    CSRFToken     string       `header:"X-CSRF-Token"`
}

//encore:api auth method=POST path=/logout
func Logout(ctx context.Context, params *AuthParams) error {
    // Access params.SessionCookie.Value
    return nil
}

Raw Endpoints

Use //encore:api raw for webhooks or direct HTTP access:

import "net/http"

//encore:api public raw path=/webhooks/stripe method=POST
func StripeWebhook(w http.ResponseWriter, req *http.Request) {
    sig := req.Header.Get("Stripe-Signature")
    // Handle raw request...
    w.WriteHeader(http.StatusOK)
}

Response Types

Standard Response

type Response struct {
    Message string `json:"message"`
}

//encore:api public method=GET path=/hello
func Hello(ctx context.Context) (*Response, error) {
    return &Response{Message: "Hello, World!"}, nil
}

No Response Body

//encore:api public method=DELETE path=/users/:id
func DeleteUser(ctx context.Context, params *DeleteParams) error {
    // Return only error (no response body on success)
    return nil
}

No Request Parameters

//encore:api public method=GET path=/health
func Health(ctx context.Context) (*HealthResponse, error) {
    return &HealthResponse{Status: "ok"}, nil
}

Error Handling

Use errs package for proper HTTP error responses:

import "encore.dev/beta/errs"

//encore:api public method=GET path=/users/:id
func GetUser(ctx context.Context, params *GetUserParams) (*User, error) {
    user, err := findUser(params.ID)
    if err != nil {
        return nil, err
    }
    if user == nil {
        return nil, &errs.Error{
            Code:    errs.NotFound,
            Message: "user not found",
        }
    }
    return user, nil
}

Common Error Codes

Code	HTTP Status	Usage
`errs.NotFound`	404	Resource doesn't exist
`errs.InvalidArgument`	400	Bad input
`errs.Unauthenticated`	401	Missing/invalid auth
`errs.PermissionDenied`	403	Not allowed
`errs.AlreadyExists`	409	Duplicate resource

Guidelines

Use //encore:api annotation above the function
Request params must be a pointer to a struct or omitted
Response must be a pointer to a struct (or omit for no body)
Always return error as the last return value
Use struct tags for JSON field names, query params, and headers
Path parameters are automatically mapped to struct fields by name