# encore.dev

## Interfaces

### APICallMeta

Describes an API call being processed.

#### Properties

##### api

`api: APIDesc`

Describes the API Endpoint being called.

##### headers

`headers: Record<string, string | string[]>`

The request headers from the HTTP request.
The values are arrays if the header contains multiple values,
either separated by ";" or when the header key appears more than once.

##### method

`method: Method`

The HTTP method used in the API call.

##### middlewareData?

`optional middlewareData?: Record<string, any>`

Contains values set in middlewares via `MiddlewareRequest.data`.

##### parsedPayload?

`optional parsedPayload?: Record<string, any>`

The parsed request payload, as expected by the application code.
Not provided for raw endpoints or when the API endpoint expects no
request data.

##### path

`path: string`

The request URL path used in the API call,
excluding any query string parameters.
For example "/path/to/endpoint".

##### pathAndQuery

`pathAndQuery: string`

The request URL path used in the API call,
including any query string parameters.
For example "/path/to/endpoint?with=querystring".

##### pathParams

`pathParams: Record<string, any>`

The parsed path parameters for the API endpoint.
The keys are the names of the path parameters,
from the API definition.

For example \{id: 5\}.

##### type

`type: "api-call"`

Specifies that the request is an API call.

***

### APIDesc

Describes an API endpoint.

#### Properties

##### auth

`auth: boolean`

Whether the endpoint requires auth.

##### endpoint

`endpoint: string`

The name of the endpoint itself.

##### raw

`raw: boolean`

Whether the endpoint is a raw endpoint.

##### service

`service: string`

The name of the service that the endpoint belongs to.

##### tags

`tags: string[]`

Tags specified on the endpoint.

***

### AppMeta

Describes the running Encore application.

#### Properties

##### apiBaseUrl

`apiBaseUrl: string`

The base URL which can be used to call the API of this running application.

For local development it is "http://localhost:&lt;port>", typically "http://localhost:4000".

If a custom domain is used for this environment it is returned here, but note that
changes only take effect at the time of deployment while custom domains can be updated at any time.

##### appId

`appId: string`

The Encore application ID. If the application is not linked to the Encore platform this will be an empty string.
To link to the Encore platform run `encore app link` from your terminal in the root directory of the Encore app.

##### build

`build: BuildMeta`

Information about the build.

##### deploy

`deploy: DeployMeta`

Information about the deployment.

##### environment

`environment: EnvironmentMeta`

Information about the environment the app is running in.

***

### BaseRequestMeta

Common fields shared by all request meta types.

#### Properties

##### trace?

`optional trace?: TraceData`

Information about the trace, if the request is being traced

***

### BuildMeta

Information about the build that formed the running application.

#### Properties

##### revision

`revision: string`

The git commit that formed the base of this build.

##### uncommittedChanges

`uncommittedChanges: boolean`

Whether there were uncommitted changes on top of the commit.

***

### DeployMeta

Information about the deployment of the running application.

#### Properties

##### hostedServices

`hostedServices: Record<string, HostedService>`

The services hosted by this deployment, keyed by the service name.

##### id

`id: string`

The unique id of the deployment. Generated by the Encore Platform.

***

### EnvironmentMeta

Describes the environment the Encore application is running in.

#### Properties

##### cloud

`cloud: CloudProvider`

The cloud this is running in.
For local development it is "local".

##### name

`name: string`

The name of environment that this application.
For local development it is "local".

##### type

`type: EnvironmentType`

The type of environment is this application running in.
For local development it is "development".

***

### HostedService

#### Properties

##### name

`name: string`

The name of the service

***

### PubSubMessageMeta

Describes a Pub/Sub message being processed.

#### Properties

##### deliveryAttempt

`deliveryAttempt: number`

The delivery attempt. The first attempt starts at 1,
and increases by 1 for each retry.

##### messageId

`messageId: string`

The unique id of the Pub/Sub message.
It is the same id returned by `topic.publish()`.
The message id stays the same across delivery attempts.

##### parsedPayload?

`optional parsedPayload?: Record<string, any>`

The parsed request payload, as expected by the application code.

##### service

`service: string`

The service processing the message.

##### subscription

`subscription: string`

The name of the Pub/Sub subscription.

##### topic

`topic: string`

The name of the Pub/Sub topic.

##### type

`type: "pubsub-message"`

Specifies that the request is a Pub/Sub message.

***

### TraceData

Provides information about the active trace.

#### Properties

##### extCorrelationId?

`optional extCorrelationId?: string`

The external correlation id provided when the trace
was created, if any.
For example via the `Request-Id` or `X-Correlation-Id` headers.

##### parentSpanId?

`optional parentSpanId?: string`

The span that initiated this span, if any.

##### parentTraceId?

`optional parentTraceId?: string`

The trace id that initiated this trace, if any.

##### spanId

`spanId: string`

The current span id.

##### traceId

`traceId: string`

The trace id.

## Type Aliases

### CloudProvider

`type CloudProvider = "aws" | "gcp" | "azure" | "encore" | "local"`

Describes what cloud provider the application is running in.

***

### EnvironmentType

`type EnvironmentType = "production" | "development" | "ephemeral" | "test"`

Describes what type of environment the application is running in.

***

### Method

```ts
type Method = 
  | "GET"
  | "POST"
  | "PUT"
  | "PATCH"
  | "DELETE"
  | "HEAD"
  | "OPTIONS"
  | "CONNECT"
  | "TRACE";
```

***

### RequestMeta

`type RequestMeta = APICallMeta | PubSubMessageMeta & BaseRequestMeta`

Describes an API call or Pub/Sub message being processed.

## Functions

### appMeta()

`function appMeta(): AppMeta`

Returns metadata about the running Encore application.

The metadata is cached and is the same object each call,
and therefore must not be modified by the caller.

#### Returns

[`AppMeta`](#appmeta)

***

### currentRequest()

`function currentRequest(): RequestMeta | undefined`

Returns information about the running Encore request,
such as API calls and Pub/Sub messages being processed.

Returns undefined only if no request is being processed,
such as during system initialization.

#### Returns

[`RequestMeta`](#requestmeta) \| `undefined`
