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

# 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 {#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*](/vault-sdk/references/java-sdk-service-account/).

# Web API Info {#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 {#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 {#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 {#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"></Endpoint>
For example, the following annotation sets an `endpointName` value of `my_endpoint_name`.

```
@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"></Endpoint>
# Requests {#requests}

Custom APIs only allow <span class="label label-warning">POST</span>  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 {#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.

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

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

```

# Errors {#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`.

```
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:

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

```

# Versioning {#versioning}

Developers are responsible for versioning their changes.

# Limits & Restrictions {#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](/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](/commercial/vault-sdk/entry-points/actions/debugging-actions)  
**Next:** [Email Processors](/commercial/vault-sdk/entry-points/email-processors)