# Create Actor


```
POST 
https://api.apify.com/v2/acts
```


Creates a new Actor with settings specified in an Actor object passed as JSON in the POST payload. The response is the full Actor object as returned by the  endpoint.

The HTTP request must have the `Content-Type: application/json` HTTP header!

The Actor needs to define at least one version of the source code. For more information, see .

If you want to make your Actor [public](https://docs.apify.com/platform/actors/publishing) using `isPublic: true`, you will need to provide the Actor's `title` and the `categories` under which that Actor will be classified in Apify Store. For this, it's best to use the [constants from our apify-shared-js package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471).

## Request

<!-- -->

### Body**required**

* **name** string | null nullable\
  **Example:** `MyActor`

* **description** string | null nullable\
  **Example:** `My favourite actor!`

* **title** string | null nullable\
  **Example:** `My actor`

* **isPublic** boolean | null nullable\
  **Example:** `false`

* **seoTitle** string | null nullable\
  **Example:** `My actor`

* **seoDescription** string | null nullable\
  **Example:** `My actor is the best`

* **restartOnError** boolean deprecated\
  **Example:** `false`

* **versions** object\[]

  * **versionNumber** string required\
    **Example:** `0.0`

  * **sourceType** object required

    * anyOf

      * VersionSourceType
      * null

      VersionSourceType (string)

      **Possible values:** \[`SOURCE_FILES`, `GIT_REPO`, `TARBALL`, `GITHUB_GIST`]

  * **envVars** object\[]

    * **name** string required\
      **Example:** `MY_ENV_VAR`
    * **value** string\
      **Example:** `my-value`
    * **isSecret** boolean | null nullable\
      **Example:** `false`

  * **applyEnvVarsToBuild** boolean | null nullable\
    **Example:** `false`

  * **buildTag** string\
    **Example:** `latest`

  * **sourceFiles** object\[]

    * anyOf

      * SourceCodeFile
      * SourceCodeFolder

      **format** SourceCodeFileFormat (string) required

      **Possible values:** \[`BASE64`, `TEXT`]

      **Example:** `TEXT`

    * **content** string required\
      **Example:** `console.log('This is the main.js file');`

    * **name** string required\
      **Example:** `src/main.js`

  * **gitRepoUrl** string | null nullable

    URL of the Git repository when sourceType is GIT\_REPO.

  * **tarballUrl** string | null nullable

    URL of the tarball when sourceType is TARBALL.

  * **gitHubGistUrl** string | null nullable

    URL of the GitHub Gist when sourceType is GITHUB\_GIST.

* **pricingInfos** object\[]

  * oneOf

    * PayPerEventActorPricingInfo
    * PricePerDatasetItemActorPricingInfo
    * FlatPricePerMonthActorPricingInfo
    * FreeActorPricingInfo

    **apifyMarginPercentage** number required

    In \[0, 1], fraction of pricePerUnitUsd that goes to Apify

  * **createdAt** string\<date-time> required

    When this pricing info record has been created

  * **startedAt** string\<date-time> required

    Since when is this pricing info record effective for a given Actor

  * **notifiedAboutFutureChangeAt** string,null\<date-time> nullable

  * **notifiedAboutChangeAt** string,null\<date-time> nullable

  * **reasonForChange** string | null nullable

  * **pricingModel** PricingModel (string) required

    **Possible values:** \[`PAY_PER_EVENT`, `PRICE_PER_DATASET_ITEM`, `FLAT_PRICE_PER_MONTH`, `FREE`]

  * **pricingPerEvent** object required

    * **actorChargeEvents** object

      * **property name\*** ActorChargeEvent

        * **eventPriceUsd** number required
        * **eventTitle** string required
        * **eventDescription** string required

  * **minimalMaxTotalChargeUsd** number | null nullable

* **categories** string\[] nullable

* **defaultRunOptions** object

  * **build** string\
    **Example:** `latest`

  * **timeoutSecs** integer\
    **Example:** `3600`

  * **memoryMbytes** integer\
    **Example:** `2048`

  * **restartOnError** boolean\
    **Example:** `false`

  * **maxItems** integer | null nullable

  * **forcePermissionLevel** object

    * anyOf

      * ActorPermissionLevel
      * null

      ActorPermissionLevel (string)

      Determines permissions that the Actor requires to run. For more information, see the [Actor permissions documentation](https://docs.apify.com/platform/actors/development/permissions).

      **Possible values:** \[`LIMITED_PERMISSIONS`, `FULL_PERMISSIONS`]

      **Example:** `LIMITED_PERMISSIONS`

* **actorStandby** object

  * anyOf
    * ActorStandby
    * null
    **isEnabled** boolean | null nullable
  * **desiredRequestsPerActorRun** integer | null nullable
  * **maxRequestsPerActorRun** integer | null nullable
  * **idleTimeoutSecs** integer | null nullable
  * **build** string | null nullable
  * **memoryMbytes** integer | null nullable
  * **disableStandbyFieldsOverride** boolean | null nullable
  * **shouldPassActorInput** boolean | null nullable

* **exampleRunInput** object

  * anyOf
    * exampleRunInput
    * null
    **body** string\
    **Example:** `{ "helloWorld": 123 }`
  * **contentType** string\
    **Example:** `application/json; charset=utf-8`

* **isDeprecated** boolean | null nullable

### Status 201

**Response Headers**

* **Location**


```
{
  "data": {
    "id": "zdc3Pyhyz3m8vjDeM",
    "userId": "wRsJZtadYvn4mBZmm",
    "name": "MyActor",
    "username": "jane35",
    "description": "My favourite Actor!",
    "isPublic": false,
    "createdAt": "2019-07-08T11:27:57.401Z",
    "modifiedAt": "2019-07-08T14:01:05.546Z",
    "stats": {
      "totalBuilds": 9,
      "totalRuns": 16,
      "totalUsers": 6,
      "totalUsers7Days": 2,
      "totalUsers30Days": 6,
      "totalUsers90Days": 6,
      "totalMetamorphs": 2,
      "lastRunStartedAt": "2019-07-08T14:01:05.546Z"
    },
    "versions": [
      {
        "versionNumber": "0.1",
        "envVars": null,
        "sourceType": "SOURCE_FILES",
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "sourceFiles": []
      },
      {
        "versionNumber": "0.2",
        "sourceType": "GIT_REPO",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "gitRepoUrl": "https://github.com/jane35/my-actor"
      },
      {
        "versionNumber": "0.3",
        "sourceType": "TARBALL",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "tarballUrl": "https://github.com/jane35/my-actor/archive/master.zip"
      },
      {
        "versionNumber": "0.4",
        "sourceType": "GITHUB_GIST",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "gitHubGistUrl": "https://gist.github.com/jane35/e51feb784yu89"
      }
    ],
    "defaultRunOptions": {
      "build": "latest",
      "timeoutSecs": 3600,
      "memoryMbytes": 2048,
      "restartOnError": false
    },
    "exampleRunInput": {
      "body": "{ \"helloWorld\": 123 }",
      "contentType": "application/json; charset=utf-8"
    },
    "isDeprecated": false,
    "deploymentKey": "ssh-rsa AAAA ...",
    "title": "My Actor",
    "taggedBuilds": {
      "latest": {
        "buildId": "z2EryhbfhgSyqj6Hn",
        "buildNumber": "0.0.2",
        "finishedAt": "2019-06-10T11:15:49.286Z"
      }
    }
  }
}
```


**Schema**

* **data** object required

  * **id** string required\
    **Example:** `zdc3Pyhyz3m8vjDeM`

  * **userId** string required\
    **Example:** `wRsJZtadYvn4mBZmm`

  * **name** string required\
    **Example:** `MyActor`

  * **username** string required\
    **Example:** `jane35`

  * **description** string | null nullable\
    **Example:** `My favourite actor!`

  * **restartOnError** boolean deprecated\
    **Example:** `false`

  * **isPublic** boolean required\
    **Example:** `false`

  * **actorPermissionLevel** ActorPermissionLevel (string)

    Determines permissions that the Actor requires to run. For more information, see the [Actor permissions documentation](https://docs.apify.com/platform/actors/development/permissions).

    **Possible values:** \[`LIMITED_PERMISSIONS`, `FULL_PERMISSIONS`]

    **Example:** `LIMITED_PERMISSIONS`

  * **createdAt** string\<date-time> required\
    **Example:** `2019-07-08T11:27:57.401Z`

  * **modifiedAt** string\<date-time> required\
    **Example:** `2019-07-08T14:01:05.546Z`

  * **stats** object required

    * **totalBuilds** integer\
      **Example:** `9`
    * **totalRuns** integer\
      **Example:** `16`
    * **totalUsers** integer\
      **Example:** `6`
    * **totalUsers7Days** integer\
      **Example:** `2`
    * **totalUsers30Days** integer\
      **Example:** `6`
    * **totalUsers90Days** integer\
      **Example:** `6`
    * **totalMetamorphs** integer\
      **Example:** `2`
    * **lastRunStartedAt** string\<date-time>\
      **Example:** `2019-07-08T14:01:05.546Z`

  * **versions** object\[] required

    * **versionNumber** string required\
      **Example:** `0.0`

    * **sourceType** object required

      * anyOf

        * VersionSourceType
        * null

        VersionSourceType (string)

        **Possible values:** \[`SOURCE_FILES`, `GIT_REPO`, `TARBALL`, `GITHUB_GIST`]

    * **envVars** object\[]

      * **name** string required\
        **Example:** `MY_ENV_VAR`
      * **value** string\
        **Example:** `my-value`
      * **isSecret** boolean | null nullable\
        **Example:** `false`

    * **applyEnvVarsToBuild** boolean | null nullable\
      **Example:** `false`

    * **buildTag** string\
      **Example:** `latest`

    * **sourceFiles** object\[]

      * anyOf

        * SourceCodeFile
        * SourceCodeFolder

        **format** SourceCodeFileFormat (string) required

        **Possible values:** \[`BASE64`, `TEXT`]

        **Example:** `TEXT`

      * **content** string required\
        **Example:** `console.log('This is the main.js file');`

      * **name** string required\
        **Example:** `src/main.js`

    * **gitRepoUrl** string | null nullable

      URL of the Git repository when sourceType is GIT\_REPO.

    * **tarballUrl** string | null nullable

      URL of the tarball when sourceType is TARBALL.

    * **gitHubGistUrl** string | null nullable

      URL of the GitHub Gist when sourceType is GITHUB\_GIST.

  * **pricingInfos** object\[]

    * oneOf

      * PayPerEventActorPricingInfo
      * PricePerDatasetItemActorPricingInfo
      * FlatPricePerMonthActorPricingInfo
      * FreeActorPricingInfo

      **apifyMarginPercentage** number required

      In \[0, 1], fraction of pricePerUnitUsd that goes to Apify

    * **createdAt** string\<date-time> required

      When this pricing info record has been created

    * **startedAt** string\<date-time> required

      Since when is this pricing info record effective for a given Actor

    * **notifiedAboutFutureChangeAt** string,null\<date-time> nullable

    * **notifiedAboutChangeAt** string,null\<date-time> nullable

    * **reasonForChange** string | null nullable

    * **pricingModel** PricingModel (string) required

      **Possible values:** \[`PAY_PER_EVENT`, `PRICE_PER_DATASET_ITEM`, `FLAT_PRICE_PER_MONTH`, `FREE`]

    * **pricingPerEvent** object required

      * **actorChargeEvents** object

        * **property name\*** ActorChargeEvent

          * **eventPriceUsd** number required
          * **eventTitle** string required
          * **eventDescription** string required

    * **minimalMaxTotalChargeUsd** number | null nullable

  * **defaultRunOptions** object required

    * **build** string\
      **Example:** `latest`

    * **timeoutSecs** integer\
      **Example:** `3600`

    * **memoryMbytes** integer\
      **Example:** `2048`

    * **restartOnError** boolean\
      **Example:** `false`

    * **maxItems** integer | null nullable

    * **forcePermissionLevel** object

      * anyOf

        * ActorPermissionLevel
        * null

        ActorPermissionLevel (string)

        Determines permissions that the Actor requires to run. For more information, see the [Actor permissions documentation](https://docs.apify.com/platform/actors/development/permissions).

        **Possible values:** \[`LIMITED_PERMISSIONS`, `FULL_PERMISSIONS`]

        **Example:** `LIMITED_PERMISSIONS`

  * **exampleRunInput** object

    * anyOf
      * exampleRunInput
      * null
      **body** string\
      **Example:** `{ "helloWorld": 123 }`
    * **contentType** string\
      **Example:** `application/json; charset=utf-8`

  * **isDeprecated** boolean | null nullable\
    **Example:** `false`

  * **deploymentKey** string\
    **Example:** `ssh-rsa AAAA ...`

  * **title** string | null nullable\
    **Example:** `My Actor`

  * **taggedBuilds** object

    * anyOf

      * TaggedBuilds
      * null

      object

      A dictionary mapping build tag names (e.g., "latest", "beta") to their build information.

      **Example:** `{"latest":{"buildId":"z2EryhbfhgSyqj6Hn","buildNumber":"0.0.2","finishedAt":"2019-06-10T11:15:49.286Z"},"beta":{"buildId":"abc123def456","buildNumber":"1.0.0-beta","finishedAt":"2019-07-15T14:30:00.000Z"}}`

  * **actorStandby** object

    * anyOf
      * ActorStandby
      * null
      **isEnabled** boolean | null nullable
    * **desiredRequestsPerActorRun** integer | null nullable
    * **maxRequestsPerActorRun** integer | null nullable
    * **idleTimeoutSecs** integer | null nullable
    * **build** string | null nullable
    * **memoryMbytes** integer | null nullable
    * **disableStandbyFieldsOverride** boolean | null nullable
    * **shouldPassActorInput** boolean | null nullable

  * **readmeSummary** string

    A brief, LLM-generated readme summary

### Status 400

Bad request - invalid input parameters or request body.


```
{
  "error": {
    "type": "invalid-input",
    "message": "Invalid input: The request body contains invalid data."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 401

Unauthorized - authentication required or invalid token.


```
{
  "error": {
    "type": "token-not-valid",
    "message": "Authentication token is not valid."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 403

Forbidden - insufficient permissions to perform this action.


```
{
  "error": {
    "type": "permission-denied",
    "message": "You do not have permission to perform this action."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 405

Method not allowed.


```
{
  "error": {
    "type": "method-not-allowed",
    "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET"
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 413

Payload too large - the request body exceeds the size limit.


```
{
  "error": {
    "type": "request-too-large",
    "message": "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 415

Unsupported media type - the Content-Encoding of the request is not supported.


```
{
  "error": {
    "type": "unsupported-content-encoding",
    "message": "Content-Encoding \"bla\" is not supported."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 429

Too many requests - rate limit exceeded.


```
{
  "error": {
    "type": "rate-limit-exceeded",
    "message": "You have exceeded the rate limit. Please try again later."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`