**Source URL:** https://limited.veevavault.dev/regulatory/vault-sdk/entry-points/custom-api

# Custom APIs

Beginning in v24.3, developers can create custom API endpoints using the `WebApi` entry point. A custom API is a Java class that implements the `WebApi` interface and uses the `@ExecuteAsUser` and `@WebApiInfo` annotations.

# Executing User

By default, custom API requests execute as the request owner, which is the authenticated user. To instead run your custom API with *Vault Owner* access, use the [`@ExecuteAs`](/vault-sdk/references/java-sdk-service-account/#ExecuteAs) annotation to run the custom API as the [*Java SDK Service Account*](/regulatory/vault-sdk/references/java-sdk-service-account/).

# Web API Info

You must specify the following in the `WebApiInfo` annotation:

*   `endpointName`: A String containing the endpoint name, which is used in the URI. Must be snake case, for example, `my_endpoint_name`.
*   `minimumVersion`: A String containing the minimum Vault API version required to use the custom API. For example, `v24.3`. Calling a custom API with a version lower than the minimum results in a failure.
*   `apiGroup`: The `Webapigroup` the API belongs to. This determines the permission set required to use the API.

# Web API Groups

Each custom API must be assigned to a Web API Group. Admins can manage Web API Groups from **Admin > Configuration > Web API Groups**.

You can create Web API Groups using the MDL `Webapigroup` component.

```
RECREATE Webapigroup my_apis__c ( 
label('My APIs'), 
description('A group for my custom Apis');
```

Each Vault can have up to 100 `Webapigroup`s.

# Permission Sets

Web API Groups must be assigned to Permission Sets. Admins can manage user access to Web API Groups from **Admin > Users & Groups > Permission Sets > {permission\_set} > API**.

# URI

The URI is determined by the `endpointName` value set in the `WebApiInfo` annotation in the following format:

<Endpoint path="https://{vaultDNS}/api/{version}/custom/{endpointName}" method="POST" />

For example, the following annotation sets an `endpointName` value of `my_endpoint_name`.

```java
@WebApiInfo(endpointName = "my_endpoint_name", minimumVersion = "v24.3", apiGroup = "my_api_group__c")
```

In a Vault with the DNS `myvault.veevavault.com`, this creates a custom endpoint with the following URI:

<Endpoint path="https://myvault.veevavault.com/api/v24.3/custom/my_endpoint_name" method="POST" />

# Requests

Custom APIs only allow POST requests and accept either valid `application/json` or `multipart/form-data` input. Requests can include one (1) binary content file, but binary content cannot be read or parsed using the Vault Java SDK.

# Responses

Custom APIs always return a status code of 200 and must return a response status of either `SUCCESS`, `FAILURE`, or `WARNING`. You can create JSON data as response binary content or return a `FileReference`.

The following example creates a response with a JSON payload.

```java
JsonObject data = jsonObjectBuilder.build();

return webApiContext.newWebApiResponseBuilder()
    .withData(data)
    .withResponseStatus(WebApiResponseStatus.SUCCESS)
    .build();
```

# Errors

You can use `WebApiError.Builder` to set custom error types and messages for your custom API to return when the response status is `FAILURE`. Add your custom errors to `FAILURE` responses using `WebApiFailureResponse.Builder`.

```java
return webApiContext.newWebApiFailureBuilder()
    .withErrors(
        VaultCollections.asList(
            webApiContext.newWebApiErrorBuilder()
                .withType("MY_CUSTOM_ERROR_TYPE")
                .withMessage("A custom error occured")
                .build()
        )
    ).build();
```

The example above creates the following response:

```java
{
    "responseStatus": "FAILURE",
    "errors":[
       {
        "type":"MY_CUSTOM_ERROR_TYPE",
        "message":"A custom error occured"
       }
    ]
}
```

# Versioning

Developers are responsible for versioning their changes.

# Limits & Restrictions

Custom APIs are subject to all current Vault Java SDK and Vault API limits, including the [Burst Limit and Auth API Burst Limit](/regulatory/vault-api/references/api-rate-limits/). Additionally, Vault processes only one (1) concurrent thread per user. Up to 20 additional requests per user will be added to a queue. After reaching the limit of 20 requests in the wait queue, subsequent requests from the same user return an error.

Developers can create a maximum of 100 custom APIs and 100 Web API Groups.

Input and output payloads are limited to 4 GB for binary content or 30 MB for JSON.

---

**Previous:** [Debugging Actions](/regulatory/vault-sdk/entry-points/actions/debugging-actions)  
**Next:** [Email Processors](/regulatory/vault-sdk/entry-points/email-processors)