Tip: Use one of the quick start templates to get started. All the necessary files are already in the project folder, pre-configured and ready to go. They also contain an AGENTS.md file for all the vibe coders in the world.
Core plumbing (templates handle this)
These files are essential, but templates set them up correctly. Unless you have specific requirements, you can leave them alone.
Dockerfile
Actors run as Docker images, and the Dockerfile tells Docker how to build yours. The templates include sensible defaults that work for most cases.
If you're curious or need custom configuration, read more about different Dockerfile variants.
package.json / requirements.txt
package.json tells Node.js what libraries the Actor needs (specifically, what happens when you run npm start). Templates include a working version that points to your main file. Read more about the package.json specification.
If you pick a Python template, dependencies are in requirements.txt. Read more about requirements.txt.
Your Actor's identity (quick setup)
This is where you make the Actor yours. A few minutes of setup here and you're good to go.
actor.json
This file tells Apify how to display and run your Actor. The most minimal version looks like this:
{
"actorSpecification": 1,
"name": "name-of-your-actor",
"version": "0.0"
}
The specification version is always 1. Choose whatever name and versioning scheme makes sense for your project.
Beyond these basics, there are dozens of optional properties for fine-tuning how your Actor appears and behaves in the Store.
Your users' experience (invest here)
These files are what your users actually see and interact with. This is where quality matters most.
Input schema
Without an input schema, users see a blank JSON text field and have to guess what inputs your Actor accepts. Not ideal.
Add "input": "./input_schema.json" to your actor.json and create the file, and suddenly your users get a proper form with dropdowns, checkboxes, text fields - whatever input types make sense for your Actor. This makes your Actor accessible to non-technical users too.
Don't want to write JSON by hand? Use this visual editor to build your schema by clicking.
Output schema
Once you've defined what goes in, define what comes out. Output schemas serve two purposes: they describe the data returned directly in your Actor's run response, and they define the structure of data stored in datasets or key-value stores.
When multiple Actors exist for the same use case, clear output schemas help users compare options and understand exactly what data they'll get from yours.
Add "output": "./output_schema.json" to your actor.json to describe your run response data. You can also define separate schemas for dataset and key-value store outputs, or indicate no output if your Actor performs automation without returning data.
README.md
Your README isn't just documentation - it's your Actor's storefront. It appears both in your source code and on your Actor's Store profile, and it's often the deciding factor when users choose between similar Actors.
A quality README includes:
What the Actor does and why someone would use it
Examples of real usage
What the output looks like and how to use it
Troubleshooting tips
This is your main marketing tool and your user manual rolled into one. Make it good.