Version: 11.x

HTTP RPC Specification

Methods <-> Type mapping

HTTP Method	Mapping	Notes
`GET`	`.query()`	Input JSON-stringified in query param. e.g. `myQuery?input=${encodeURIComponent(JSON.stringify(input))}`
`POST`	`.mutation()`	Input as POST body.
n/a	`.subscription()`	Subscriptions are not supported in HTTP transport

Accessing nested procedures

Nested procedures are separated by dots, so for a request to byId below would end up being a request to /api/trpc/post.byId.

ts
export const appRouter = router({
  post: router({
    byId: publicProcedure.input(String).query(async (opts) => {
      // [...]
    }),
  }),
});

ts
export const appRouter = router({
  post: router({
    byId: publicProcedure.input(String).query(async (opts) => {
      // [...]
    }),
  }),
});

Batching

When batching, we combine all parallel procedure calls of the same HTTP method in one request using a data loader.

The called procedures' names are combined by a comma (,) in the pathname
Input parameters are sent as a query parameter called input which has the shape Record<number, unknown>.
We also need to pass batch=1 as a query parameter.
If the response has different statuses, we send back 207 Multi-Status (e.g., if one call errored and one succeeded)

Batching Example Request

Given a router like this exposed at `/api/trpc`:

server/router.ts
tsx
export const appRouter = t.router({
  postById: t.procedure.input(String).query(async (opts) => {
    const post = await opts.ctx.post.findUnique({
      where: { id: opts.input },
    });
    return post;
  }),
  relatedPosts: t.procedure.input(String).query(async (opts) => {
    const posts = await opts.ctx.findRelatedPostsById(opts.input);
    return posts;
  }),
});

server/router.ts
tsx
export const appRouter = t.router({
  postById: t.procedure.input(String).query(async (opts) => {
    const post = await opts.ctx.post.findUnique({
      where: { id: opts.input },
    });
    return post;
  }),
  relatedPosts: t.procedure.input(String).query(async (opts) => {
    const posts = await opts.ctx.findRelatedPostsById(opts.input);
    return posts;
  }),
});

... And two queries defined like this in a React component:

MyComponent.tsx
tsx
export function MyComponent() {
  const post1 = trpc.postById.useQuery('1');
  const relatedPosts = trpc.relatedPosts.useQuery('1');
  return (
    <pre>
      {JSON.stringify(
        {
          post1: post1.data ?? null,
          relatedPosts: relatedPosts.data ?? null,
        },
        null,
        4,
      )}
    </pre>
  );
}

MyComponent.tsx
tsx
export function MyComponent() {
  const post1 = trpc.postById.useQuery('1');
  const relatedPosts = trpc.relatedPosts.useQuery('1');
  return (
    <pre>
      {JSON.stringify(
        {
          post1: post1.data ?? null,
          relatedPosts: relatedPosts.data ?? null,
        },
        null,
        4,
      )}
    </pre>
  );
}

The above would result in exactly 1 HTTP call with this data:

Location property	Value
`pathname`	`/api/trpc/postById,relatedPosts`
`search`	`?batch=1&input=%7B%220%22%3A%221%22%2C%221%22%3A%221%22%7D` *

*) input in the above is the result of:

ts
encodeURIComponent(
  JSON.stringify({
    0: '1', // <-- input for `postById`
    1: '1', // <-- input for `relatedPosts`
  }),
);

ts
encodeURIComponent(
  JSON.stringify({
    0: '1', // <-- input for `postById`
    1: '1', // <-- input for `relatedPosts`
  }),
);

Batching Example Response

Example output from server

HTTP Response Specification

In order to have a specification that works regardless of the transport layer we try to conform to JSON-RPC 2.0 where possible.

Successful Response

Example JSON Response

ts
{
  result: {
    data: TOutput; // output from procedure
  }
}

ts
{
  result: {
    data: TOutput; // output from procedure
  }
}

Error Response

Example JSON Response

When possible, we propagate HTTP status codes from the error thrown.
If the response has different statuses, we send back 207 Multi-Status (e.g., if one call errored and one succeeded)
For more on errors and how to customize them see Error Formatting.

Error Codes <-> HTTP Status

ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
UNAUTHORIZED: 401,
NOT_FOUND: 404,
FORBIDDEN: 403,
METHOD_NOT_SUPPORTED: 405,
TIMEOUT: 408,
CONFLICT: 409,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
UNPROCESSABLE_CONTENT: 422,
TOO_MANY_REQUESTS: 429,
CLIENT_CLOSED_REQUEST: 499,
INTERNAL_SERVER_ERROR: 500,
NOT_IMPLEMENTED: 501,

ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
UNAUTHORIZED: 401,
NOT_FOUND: 404,
FORBIDDEN: 403,
METHOD_NOT_SUPPORTED: 405,
TIMEOUT: 408,
CONFLICT: 409,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
UNPROCESSABLE_CONTENT: 422,
TOO_MANY_REQUESTS: 429,
CLIENT_CLOSED_REQUEST: 499,
INTERNAL_SERVER_ERROR: 500,
NOT_IMPLEMENTED: 501,

Error Codes <-> JSON-RPC 2.0 Error Codes

Available codes & JSON-RPC code

Dig deeper

You can read more details by drilling into the TypeScript definitions in

Methods <-> Type mapping​

Accessing nested procedures​

Batching​

Batching Example Request​

Given a router like this exposed at /api/trpc:​

... And two queries defined like this in a React component:​

The above would result in exactly 1 HTTP call with this data:​

Batching Example Response​

HTTP Response Specification​

Successful Response​

Error Response​

Error Codes <-> HTTP Status​

Error Codes <-> JSON-RPC 2.0 Error Codes​

Dig deeper​