> ## Documentation Index > Fetch the complete documentation index at: https://docs.canton.network/llms.txt > Use this file to discover all available pages before exploring further. # JSON Ledger API Migration to V2 guide Migration guide for existing JSON Ledger API V1 users. JSON Ledger API V2 is a mirror of a gRPC Ledger API, thus it diverges substantially in some aspects from V1 API. Some v1 endpoints have simple corresponding v2 endpoints, while some need more calls or extra processing in order to simulate v1 behavior. Chapters below only point out the endpoints that should be used in `v2`. Consult the [JSON Ledger API reference](/reference/json-api-reference/details) for exact details and usage. ## Create a New Contract * v1 endpoint: `POST` `/v1/create` * v2 equivalent: `POST` `/v2/commands/submit-and-wait` In the `JsCommands` request body, add a `CreateCommand` object (wrapping your v1 create payload) as an element of the `commands` array. There is also an alternate endpoint, `/v2/commands/submit-and-wait-for-transaction`, which can be used instead of `/v2/commands/submit-and-wait` to get more data about the processed transaction. To receive tree-equivalent data, set `transactionFormat.transactionShape` to `TRANSACTION_SHAPE_LEDGER_EFFECTS` in the request. (`/v2/commands/submit-and-wait-for-transaction-tree` is deprecated and slated for removal; do not migrate to it.) ## Create a Contract with a Command ID * v1 endpoint: `POST` `/v1/create` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "templateId": "...", "payload": { ... }, "meta": { "commandId": "my-unique-id" } } ``` * v2 equivalent: `POST` `/v2/commands/submit-and-wait` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "commandId": "my-unique-id", "actAs": ["..."], "commands": [ { "CreateCommand": { "templateId": "...", "createArguments": { ... } } } ] } ``` Same as Create a New Contract, except for where the command ID lives: in v1 it was the optional `meta.commandId` field, while in v2 `commandId` is a required top-level field of the `JsCommands` object. ## Exercise by Contract ID * v1 endpoint: `POST` `/v1/exercise` * v2 equivalent: `POST` `/v2/commands/submit-and-wait` In the `JsCommands` request body, add an `ExerciseCommand` object as an element of the `commands` array. ## Exercise by Contract Key * v1 endpoint: `POST` `/v1/exercise` (with a `key` in place of a `contractId`) * v2 equivalent: `POST` `/v2/commands/submit-and-wait` In the `JsCommands` request body, add an `ExerciseByKeyCommand` object as an element of the `commands` array. Contract keys in Canton 3.x require the template to be compiled against Daml-LF 2.3 or later (the default target is 2.2, which has no contract keys) and a synchronizer running protocol version 3.5 or later. Unlike v1, contract keys are non-unique: key uniqueness is not enforced. ## Create and Exercise in the Same Transaction * v1 endpoint: `POST` `/v1/create-and-exercise` * v2 equivalent: `POST` `/v2/commands/submit-and-wait` In the `JsCommands` request body, add a `CreateAndExerciseCommand` object as an element of the `commands` array. ## Fetch Contract by Contract ID * v1 endpoint: `POST` `/v1/fetch` * v2 equivalent: `POST` `/v2/events/events-by-contract-id` ## Fetch Contract by Key * v1 endpoint: `POST` `/v1/fetch` * v2 equivalent: no direct replacement ## Get All Active Contracts * v1 endpoint: `GET` `/v1/query` * v2 equivalent: `/v2/state/active-contracts` If you do not have desired ledger offset (`activeAtOffset`), obtain it via a call to `/v2/state/ledger-end`. There is also a streaming version of this endpoint in V2, which uses websockets. It provides better scalability for large results. Alternatively, `POST /v2/state/active-contracts-page` returns the active contract set in pages over plain HTTP. ## Get All Active Contracts Matching a Given Query * v1 endpoint: `GET` `/v1/query` * v2 equivalent: no direct replacement * Option 1: use `/v2/state/active-contracts` and query result in client code * Option 2: use PQS (suitable for more demanding use cases) ## Fetch Parties by Identifiers * v1 endpoint: `POST` `/v1/parties` * v2 equivalent: `GET` `/v2/parties/` ## Fetch All Known Parties * v1 endpoint: `GET` `/v1/parties` * v2 equivalent: `GET` `/v2/parties` ## Allocate a New Party * v1 endpoint: `POST` `/v1/parties/allocate` * v2 equivalent: `POST` `/v2/parties` ## Create a New User * v1 endpoint: `POST` `/v1/user/create` * v2 equivalent: `POST` `/v2/users` ## Get Authenticated User Information * v1 endpoint: `GET` `/v1/user` * v2 equivalent: `GET` `/v2/authenticated-user` ## Get Specific User Information * v1 endpoint: `POST` `/v1/user` * v2 equivalent: `GET` `/v2/users/` ## Delete Specific User * v1 endpoint: `POST` `/v1/user/delete` * v2 equivalent: `DELETE` `/v2/users/` ## List Users * v1 endpoint: `GET` `/v1/users` * v2 equivalent: `GET` `/v2/users` ## Grant User Rights * v1 endpoint: `POST` `/v1/user/rights/grant` * v2 equivalent: `POST` `/v2/users//rights` ## Revoke User Rights * v1 endpoint: `POST` `/v1/user/rights/revoke` * v2 equivalent: `PATCH` `/v2/users//rights` ## List Authenticated User Rights * v1 endpoint: `GET` `/v1/user/rights` * v2 equivalent: `GET` `/v2/users//rights` ## List Specific User Rights * v1 endpoint: `POST` `/v1/user/rights` * v2 equivalent: `GET` `/v2/users//rights` ## List All DALF Packages * v1 endpoint: `GET` `/v1/packages` * v2 equivalent: `GET` `/v2/packages` ## Download a DALF Package * v1 endpoint: `GET` `/v1/packages/` * v2 equivalent: `GET` `/v2/packages/` ## Upload a DAR File * v1 endpoint: `POST` `/v1/packages` * v2 equivalent: `POST` `/v2/dars` `POST /v2/packages` behaves identically; prefer `/v2/dars`. ## Metering Report * v1 endpoint: `/v1/metering-report` * v2: no direct replacement, metering has been removed ## Streaming API ### Contracts Query Stream * v1 endpoint: `websocket` `/v1/stream/query` * v2 equivalent: `websocket` `/v2/state/active-contracts` ### Fetch by Key Contracts Stream * v1 endpoint: `websocket` `/v1/stream/fetch` * v2: no direct replacement * Option 1: Use PQS * Option 2: Use `/v2/state/active-contracts` with client-side filtering (for infrequent queries).